LINUX.ORG.RU
Форум — Development  

Заставить Sphinx таки генерить документацию

 ,


0

1

То ли лыжи не едут, то ли весь мир сошёл с ума, я один Д'Артаньян. Sphinx не создаёт документацию. Проблема, насколько я сумел правильно её локализовать, в генах shpinx-apidoc. В коде docstring'и присутствуют, а в создаваемых rst'шках нет ни моих docstring'ов, ни даже упоминания используемых функций и классов. Создаются вот такие «пустые» файлы: 

master_build Package
===================

:mod:`master_build` Package
--------------------------

.. automodule:: master_build
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`master_build` Module
-------------------------

.. automodule:: master_build.master_build
    :members:
    :undoc-members:
    :show-inheritance:

Я-то ожидал увидеть документацию в которой как минимум был бы список используемых классов без описания.

Что я делаю не так?

Есть где-нибудь пошаговый пример работы с docstring'ами и sphinx'ом? В духе «пишем такой код, запускаем такую команду, получаем вот такую html'ку». Подобных примеров вроде бы полно, обычно они начинаются запуска sphinx-quickstart, но там не показывается с каким кодом это всё работает и что в итоге получается.

★★★★★

make html, при условии, что ты создал makefile. Нет, тогда man sphinx-build. Makefile, ЕМНИП, генерируется с помощью sphinx-quickstart.

Kilte ★★★★★
()
Последнее исправление: Kilte (всего исправлений: 2)
Ответ на: комментарий от Kilte

А в ответ пустота

make html

А толку? В index.html «пусто». Страница есть, но там нет упоминания ни одного модуля, функции или класса. Я так понимаю sphinx создаёт HTML из *.rst, а в них ничего. Так что надо разобраться почему sphinx-apidoc ничего не пишет в rst.

Camel ★★★★★
() автор топика
Ответ на: комментарий от Kilte

sphinx-apidoc

Тогда скидывай конфиг, как запускал и лог сборки.

sphinx-apidoc запускается без конфига.

sphinx-apidoc -o docs ./
Camel ★★★★★
() автор топика
Ответ на: sphinx-apidoc от Camel

RTFM!

Задача sphinx-apidoc просканировать модули и создать rst файлы, содержащие директивы, необходимые для вот этого расширения: http://sphinx-doc.org/ext/autodoc.html

Так что с rst у тебя всё в порядке.

Создаёшь конфиг, подключаешь расширение autodoc и выполняешь make html или sphinx-build

Возможно потребуется что-то ещё. Лучше почитай документацию или загугли руководство, где всё уже до меня разжевали.

Kilte ★★★★★
()
Ответ на: комментарий от Kilte

Ну вот что ему не так?

$ sphinx-build -b html -d _build/doctrees/ ./ _build/html/
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 5 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
usage: sphinx-build [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: sphinx-build --help [cmd1 cmd2 ...]
   or: sphinx-build --help-commands
   or: sphinx-build cmd --help

error: option -b not recognized

Какого чёрта "-b not recognized"?

Camel ★★★★★
() автор топика
Ответ на: Ну вот что ему не так? от Camel

А без -b html что говорит? html используется по умолчанию.

Честно говоря, впервые с таким сталкиваюсь. Беглый гуглинг показал, что вероятно есть какой-то конфликтующий код, выполняющийся при импортировании, который следует обернуть в условие if __name__ == '__main__':

Kilte ★★★★★
()
Ответ на: комментарий от Kilte

Python говно

А без -b html что говорит? html используется по умолчанию.

Без -b html говорит, что -d not recognized.

код...обернуть в условие if __name__ == '__main__':

Код скриптов обёрнут в это условие, код библиотечных модулей не имеет такой обёртки, но и не должен иметь (хотя может).

Честно говоря, впервые с таким сталкиваюсь.

Честно говоря, я тоже. Я кое как заставил этот кусок говна (sphinx) работать, сначала документировал Hello World складывая всё в корень, потом заставил работать с моим кодом, потом подобрал набор заклинаний для переноса документации в отдельную директорию, где ей и место. Но я совершенно не ожидал что столь необходимый инструмент для столь популярного языка окажется настолько кривым и дурно пахнущим, ошибки неожиданными, а сообщения об ошибках совершенно бесполезными. Меня не покидает мнение, что значительная часть пейтонистов говноеды.

Но в любом случае спасибо вам за помощь.

Camel ★★★★★
() автор топика
Последнее исправление: Camel (всего исправлений: 1)
Ответ на: Python говно от Camel

У большинства всё работает. Возможно имеет смысл отрепортить авторам сего поделия, может они что подскажут.

По поводу багов. Не сфинксом едины. В setuptools к примеру тоже порой странные баги возникают, которые фиксятся порядком указания зависимостей, например. Я очень удивился, что оно при поиске пакетов парсит html регулярками(!). Правда это в distutils вроде происходит, уже не помню, но сути не меняет.

Kilte ★★★★★
()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.
Development