Автоматическое создание документации для проекта Python с помощью setuptools

Я создал демонстрационный проект, который использует setuptools и имеет следующую структуру:

project/
 |- pizza/
 |   |- __init__.py
 |   `- margherita.py
 |
 |- README.rst
 |- setup.cfg
 `- setup.py

Я пытаюсь автоматически создать документацию для этого проекта с помощью Sphinx. До сих пор я пробовал:

# Generate a sphinx template
sphinx-quickstart
# Use default settings, except for project name, etc.
sphinx-apidoc -o source .
./setup.py build_sphinx

Я чувствую, что должен быть более простой способ автоматически сгенерировать эту документацию, используя README, setup.py и строки документации.

В конечном итоге я хотел бы автоматически генерировать apidocs для другого проекта, в котором я также использую Python C-api. Я не мог найти ничего для этого.

Мой главный вопрос: есть ли более простой способ автоматического создания этой документации?


python python-sphinx api-doc
person Remco Haszing    schedule 15.01.2014    source источник

Ответы (2)


arrow_upward
3
arrow_downward 

sphinx-apidoc -F -o source .

Сгенерирует проект с sphinx-quickstart и рекурсивно ищет модули python

Вы настолько эффективны, насколько можете быть в данный момент.

=== Здесь просто желаемое за действительное ===

Было бы прекрасно, если бы вы могли назвать что-то вроде

./setup.py build_sphinx -C

и он создаст вам index.RST, прочитает любые файлы RST, о которых вы спотыкались, проанализирует все строки документации и выдаст немного html.

person Chris Clarke    schedule 20.01.2014
comment
Также следующие флаги будут включать некоторые метаданные: -H $(./setup.py --name) -A $(./setup.py --author) -V $(./setup.py --version). К сожалению, это не работает для расширений C. - person Remco Haszing; 20.01.2014
comment
Извините, но это довольно простой ответ. Я не вижу никаких усилий, чтобы создать какое-то аккуратное решение. Пример, который вы приводите (/.setup.py build_sphinx -C), выглядит правильно. Это должно быть возможно так или иначе. Простое заявление об использовании sphinx-apidoc не стоит моей награды. - person siebz0r; 21.01.2014
comment
Согласен, удачи в поиске более элегантного решения. Я хотел бы знать, если вы делаете - person Chris Clarke; 21.01.2014

arrow_upward
7
arrow_downward

Чтобы расширить setup.py, чтобы он содержал дополнительную команду для Sphinx, вы можете создать пользовательскую команду. Я подготовил небольшой пример, который запускает Sphinx apidoc, а затем создает исходный код документа. Используются имя проекта, автор, версия и расположение исходных кодов, определенные в setup.py (при условии, что они определены).

class Sphinx(Command):
    user_options = []
    description = 'sphinx'

    def initialize_options(self):
        pass

    def finalize_options(self):
        pass

    def run(self):
        # metadata contains information supplied in setup()
        metadata = self.distribution.metadata
        # package_dir may be None, in that case use the current directory.
        src_dir = (self.distribution.package_dir or {'': ''})['']
        src_dir = os.path.join(os.getcwd(),  src_dir)
        # Run sphinx by calling the main method, '--full' also adds a conf.py
        sphinx.apidoc.main(
            ['', '--full', '-H', metadata.name, '-A', metadata.author,
             '-V', metadata.version, '-R', metadata.version,
             '-o', os.path.join('doc', 'source'), src_dir])
        # build the doc sources
        sphinx.main(['', os.path.join('doc', 'source'),
                     os.path.join('doc', 'build')])

Затем команду необходимо зарегистрировать в группе точек входа distutils.commands. Здесь команда называется sphinx.

from setuptools import setup

setup(
    # ...
    setup_requires = ['sphinx'],
    entry_points = {
        'distutils.commands': [
            'sphinx = example_module:Sphinx'
        ]
    }
)

Я не знаю, как обрабатываются исходники C, но это поможет вам начать.

person siebz0r    schedule 08.03.2014
comment
Это было невероятно полезно. Спасибо - person dusktreader; 25.08.2016