Не могу разобраться со 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 выглядит намного лучше:

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