Не могу разобраться со Sphinx-ом

Я месяц назад начал писать одну библиотеку для питона, и стокнулся с проблемой документирования. В качестве примера решил взять discord.py и использовать Sphinx для документации, и добавил в мой conf.py следующие переменные:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinxcontrib_trio"
]

html_theme = 'basic'

html_experimental_html5_writer = True

Мой index.rst файл:

.. currentmodule:: mylib

Welcome to dosera's documentation!
==================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. autoclass:: mainy
    :members:

.. autoclass:: SU
    :members:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

__init__.py моего тестового модуля:

class SU:
    """
    The class for using SuperUser priveledges
    
    Attributes
    ------------
    use: :class:`bool`
        Set to ``True`` if you're a SuperUser
    """
    
    use: bool = False

class mainy:
    """
    The main class for the lib
    
    Attributes
    ------------
    keys: :class:`str`
        A comma-separated list of keys
    """
    
    def run(self, num: int = 1, s: SU = None) -> int:
        """
        Runs the loop
        
        Parameters
        --------------
        num: :class:`int`
            The number returned if the loop ran successfully
        su: :class:`SU`
            The SU
        
        Returns
        ---------
        :class:`int`
            The num
        """
        return num

Использовал я стиль NumPy

Но когда я прописал py -m sphinx -b html source build/html в рут-папке проекта, результат крайне отличался от документации discord.py: Результат

В то же время документация discord.py выглядит намного лучше: Документация discord.py

Я подумал что дело в хосте документации (ReadTheDocs), но когда я склонировал репозиторий и локально сгенерировал документацию, результат был тем же, что и на хосте.

Вопросы у меня такие:

  1. Почему тип переменных и возвращаемого значения и параметры функций в документации d.py показываются на следующих строках, а у меня группируются в список, причем первое значение находится на той же строчке что и "заголовок" (типо Parameters, Returns или Return type)?
  2. Почему впринципе у меня не получилось никакой темы, почти что сырой текст, хотя в целом конфигурация схожая с конфигурацией d.py?

Ну и в целом подскажите как делать красивую документацию, заранее спасибо!


Ответы (0 шт):