Пытаюсь организовать автоматическую генерацию доки из docstrings в исходных файлах Python, используя для этого sphinx. Честно говоря - ничего не понимаю! :-(
Если в корне проекта выполнить команду make html, то генерируется только index.html в котором ни одна ссылка не работает, да и нет никаких других файлов.
Я предположил, что это от того, что в файле index.rst НЕ перечислены файлы проекта. Я их там перечилил (Питоновские, без расширений!). Ничего не изменилось
Так как sphinx работает с rst файлами, то я предполагал, что они будут автоматически генерироваться неким инструментом сфинкса. Ни фига...
Попробовал вручную сгенерировать rst по py так:
sphinx-autogen inquiry.py
Ничего не произошло. Т.е. вообще - ничего. Никаких новых файлов, никаких сообщений об ошибках - ничего!
Читая доку про сфинкс, наткнулся на страничку, где описано, "Include documentation from docstrings". (http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) Ага, это же как раз то, что мне нужно!
Но не понял - ничего :-( Какие экстеншены, куда их втыкать, в какие файлы вставлять директивы... ?!
Может мне кто-то в двух словах объяснить, как решить такую задачу:
Есть проект, который состоит из питоновских файлов
p1.py
p2.py
....
pN.py
Внутри этих файлов используются docstrings. Какие операторы разметки можно использовать внутри docstrings?
Как настроить sphinx, Makefile, conf.py и index.rst что бы введя команду make help можно было получить результат - готовую доку?
Как просто всё было в Doxygen... :-(