Названия разделов Sphinx apidoc для имен модулей/пакетов Python

Когда я запускаю sphinx-apidoc, а затем make html, он создает страницы документа, которые имеют разделы "Subpackages" и "Submodules" и "module" и "package" в конце каждого имени модуля/пакета в оглавлении (ТОС). Как я могу предотвратить использование этих дополнительных заголовков без редактирования источника Sphinx?

вот пример doc-страниц, которые я хотел бы сделать (обратите внимание на TOC):

http://selenium.googlecode.com/svn/trunk/docs/api/py/index.html#documentation

Я понимаю, что это связано с файлом apidoc.py в источнике sphinx (строка 88):

https://bitbucket.org/birkenfeld/sphinx/src/ef3092d458cc00c4b74dd342ea05ba1059a5da70/sphinx/apidoc.py?at=default

Я мог бы вручную отредактировать каждый отдельный .rst файл, чтобы удалить эти заголовки или просто удалить эти строки кода из script, но тогда мне придется скомпилировать исходный код Sphinx. Есть ли автоматический способ сделать это без ручного редактирования источника Sphinx?

Ответы

Ответ 1

Я сам боролся с этим, когда нашел этот вопрос... Ответы дали не совсем то, что я хотел, поэтому я поклялся вернуться, когда понял.:)

Чтобы удалить "пакет" и "модуль" из автоматически сгенерированных заголовков и иметь документы, которые действительно автоматические, вам необходимо внести изменения в несколько мест, которые несут меня.

Сначала вам нужно обработать ваши параметры sphinx-apidoc. Я использую:

sphinx-apidoc -fMeET ../yourpackage -o api

Предполагая, что вы запускаете это из каталога docs, это будет источником yourpackage для документации и поместить полученные файлы в docs/api. Параметры, которые я использую здесь, будут перезаписывать существующие файлы, помещать документы модуля перед документами подмодуля, размещать документацию для каждого модуля на своей странице, воздерживаться от создания заголовков модулей/пакетов, если у ваших док-строк уже есть их, и он не будет создавать файл оглавления.

Это много вариантов для запоминания, поэтому я просто добавляю это в конец моего Makefile:

buildapi:
    sphinx-apidoc -fMeET ../yourpackage -o api
    @echo "Auto-generation of API documentation finished. " \
          "The generated files are in 'api/'"

С помощью этого места вы можете просто запустить make buildapi для создания своих документов.

Затем создайте файл api.rst в корне ваших документов со следующим содержимым:

API Documentation
=================

Information on specific functions, classes, and methods.

.. toctree::
   :glob:

   api/*

Это создаст оглавление со всем, что находится в папке api.

К сожалению, sphinx-apidoc все равно сгенерирует файл yourpackage.rst с уродливым заголовком "yourpackage package", поэтому нам понадобится одна последняя часть конфигурации. В файле conf.py найдите параметр exclude_patterns и добавьте этот файл в список. Он должен выглядеть примерно так:

exclude_patterns = ['_build', 'api/yourpackage.rst']

Теперь ваша документация должна выглядеть так, как вы ее создали в модульных docstrings, и вам никогда не придется беспокоиться о том, что ваши документы Sphinx и ваша внутрикодовая документация не синхронизированы!

Ответ 2

Ответ Джен Гарсиа помог многим, но для этого требуется добавить имена повторных пакетов в docstrings. Я использовал однострочный Perl для удаления суффикса "module" или "package" в моем Makefile:

docs:
    rm -rf docs/api docs/_build
    sphinx-apidoc -MeT -o docs/api wdmapper
    for f in docs/api/*.rst; do\
        perl -pi -e 's/(module|package)$$// if $$. == 1' $$f ;\
    done
    $(MAKE) -C docs html

Ответ 4

Я не уверен, что я на 100% отвечаю на ваш вопрос, но у меня был подобный опыт, и я понял, что каждый раз я запускаю sphinx-apidoc с флагом -f, который создал файлы .rst, свежие каждый время.

Теперь я разрешаю sphinx-apidoc генерировать файлы .rst один раз, но не перезаписывать их, поэтому я могу изменить их, чтобы изменить названия /etc. а затем запустите make html для распространения изменений. Если я хочу только генерировать файлы .rst, я могу просто удалить файлы, которые я хочу восстановить, или передать флаг -f.

Итак, вам нужно изменить первые файлы, но только один раз.