Вопрос по python – Выдать reStructuredText из сфинкса автодок?

20

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

Для PEP 3144 (модуль ipaddress) я хотел бы использовать sphinx-apidoc для генерации исходной справочной документации. Это означает, что я хочу запустить двухпроходную операцию:

Используйте sphinx-apidoc для создания проекта Sphinx для модуля, который зависит от autodoc

Запустите sphinx-конструктор, который создает новые исходные файлы reStructuredText со всеми директивами autodoc, замененными встроенным содержимым и разметкой reStructuredText, которые выдают одинаковый вывод

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

@ipaddress уже есть обширные строки документов, поэтому я не хочу копировать, вставлять их и переформатировать вручную для остальных документов. ncoghlan
Так зачем их копировать? Вы можете написать свою дополнительную документацию «между» директивами auto и позволить sphinx перевести ее, не нужно копировать. Извините, возможно, я вас не понимаю (или ваш вопрос). bmu
Что плохого в том, чтобы использовать первые файлы, сгенерированные autodoc (поэтому только в авто-директивах нет полных определений py-домена) и расширять их? bmu
@ ncoghlan: Есть ли отзывы о двух ответах? Я буду награждать награду завтра. Steven Rumbalski
@ bmu В процессе сборки документации на CPython автодок не включен (по преднамеренному выбору) ncoghlan

Ваш Ответ

2   ответа
9

и одно время я создавал документы, которые использовал довольно уродливое решение для исправления Сфинкса, см. Сделайте Sphinx генерировать документацию класса RST из pydoc.

+ 1, так как я думаю, что это единственный способ полностью отформатировать первый источник с помощью autodoc. В autodoc должно быть событие для его получения. (также см. мой ответ). bmu
Спасибо, похоже, это будет хорошо работать. ncoghlan
2

autodoc переводит авто-директивы в директивы Python. Таким образом, можно использовать события autodoc для получения переведенных директив python.

Например, если у вас есть следующееmymodule.py:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
This is my module.
"""

def my_test_func(a, b=1):
    """This is my test function"""
    return a + b 

class MyClass(object):
    """This is my class"""

    def __init__(x, y='test'):
        """The init of my class"""
        self.x = float(x)
        self.y = y 

    def my_method(self, z): 
        """This is my method.

        :param z: a number
        :type z: float, int
        :returns: the sum of self.x and z
        :rtype: float
        """
        return self.x + z 

sphinx-apidoc создас

mymodule Module
===============

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

Следующее расширение (или дополнение кconf.py):

NAMES = []
DIRECTIVES = {}

def get_rst(app, what, name, obj, options, signature,
            return_annotation):
    doc_indent = '    '
    directive_indent = ''
    if what in ['method', 'attribute']:
        doc_indent += '    '
        directive_indent += '    '
    directive = '%s.. py:%s:: %s' % (directive_indent, what, name)
    if signature:  # modules, attributes, ... don't have a signature
        directive += signature
    NAMES.append(name)
    rst = directive + '\n\n' + doc_indent + obj.__doc__ + '\n'
    DIRECTIVES[name] = rst 

def write_new_docs(app, exception):
    txt = ['My module documentation']
    txt.append('-----------------------\n')
    for name in NAMES:
        txt.append(DIRECTIVES[name])
    print '\n'.join(txt)
    with open('../doc_new/generated.rst', 'w') as outfile:
        outfile.write('\n'.join(txt))

def setup(app):
    app.connect('autodoc-process-signature', get_rst)
    app.connect('build-finished', write_new_docs)

дам тебе

My module documentation
-----------------------

.. py:module:: mymodule


This is my module.


.. py:class:: mymodule.MyClass(x, y='test')

    This is my class

    .. py:method:: mymodule.MyClass.my_method(z)

        This is my method.

        :param z: a number
        :type z: float, int
        :returns: the sum of self.x and z
        :rtype: float


.. py:function:: mymodule.my_test_func(a, b=1)

    This is my test function

Как быautodoc не производит никакого события, когда перевод завершен, поэтому дальнейшая обработка, выполняемая autodoc, должна быть адаптирована к строкам документации.

Похожие вопросы