с помощью утилиты Sphinx sphinx-apidoc для автоматической генерации документации из кода python

Question

Мне интересно, какой формат комментариев используется для того, чтобы иметь самодокументирующий код, используя служебную программу sphinx-apidoc Sphinx. Я могу получить эту утилиту для создания набора файлов reStructuredText для каждого файла python, но эти файлы по-прежнему необходимо заполнить. Я ищу способ получить эту утилиту или другую служебную программу Sphinx для создания документации из коды python docstrings. Я понимаю, что это потребует ознакомления с обычным форматом комментариев, и я надеюсь, что будет указан этот справочный материал. Благодаря!

Answer 1

mzjn, спасибо за комментарий. ваша вторая ссылка предоставила некоторое представление о том, как форматировать docstrings.

Кроме того, я не смог отметить надлежащее sphinx-quickstart ответы (как указано в ссылке http://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example). В частности, отвечая да к:

AutoDoc: автоматически вставлять строки документации из модулей (Y/N) [N]:

также, как отмечалось в ссылке, http://codeandchaos.wordpress.com/2012/07/30/sphinx-autodoc-tutorial-for-dummies/ и conf.py комментариев, мне нужно было добавить расположение модулей в системный путь. Я должен заметить, что я столкнулся с проблемой добавления имен файлов. когда я добавлял пути, где могли быть найдены модули, все работало отлично.