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

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

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

Во-первых, вам нужно обработать ваши 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']

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

Возможно, уже поздно, но параметры maxdepth или titlesonly должны помочь.

Подробнее: http://sphinx-doc.org/latest/markup/toctree.html < / а>

ответ Джен Гарсиа очень помог, но для этого необходимо поместить повторяющиеся имена пакетов в строки документации. Я использовал однострочник Perl, чтобы удалить суффикс «модуль» или «пакет» в моем 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

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

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

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

Я не хотел использовать заголовки в своих строках документации, поскольку следовал рекомендациям по стилю numpy. Итак, я сначала создаю первые файлы, а затем запускаю следующий скрипт python в качестве этапа постобработки.

from pathlib import Path


src_dir = Path("source/api")
for file in src_dir.iterdir():
    print("Processed RST file:", file)
    with open(file, "r") as f:
        lines = f.read()

    junk_strs = ["Submodules\n----------", "Subpackages\n-----------"]

    for junk in junk_strs:
        lines = lines.replace(junk, "")

    lines = lines.replace(" module\n=", "\n")

    with open(file, "w") as f:
        f.write(lines)

Этот сценарий хранится в том же каталоге, что и make-файл. Я также добавляю в make-файл следующие строки.

html:
    # rm -r "$(BUILDDIR)"
    python rst_process.py
    @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Теперь при запуске make html документация строится так, как я хочу.