Сделайте SPHINX генерировать документацию RST класса из Pydoc

Question

В настоящее время я в настоящее время миграцию всей существующей (неполной) документации Сфинкс.

Проблема в том, что документация использует Python Docstrings. (Модуль написан в C, но он, вероятно, не имеет значения), а классная документация должна быть преобразована в форму, используемую для SPHINX.

Есть sphinx.ext.autodoc., но он автоматически ставит текущие DocStrings в документ. Я хочу создать исходный файл в (Первенство) на основе текущих DOCStrings, которые я мог затем редактировать и улучшаться вручную.

Как бы вы преобразуете DocStrings на RST для SPHINX?

Answer 1

Autodoc создает RST, только нет официального способа получить его из этого. Самый простой взломан, чтобы получить это был путем изменения sphinx.ext.autodoc.Documenter.add_line Метод излучает мне линию, это получает.

Как все, что я хочу, это однажды миграция, вывод на stdout достаточно хорош для меня:

def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    print self.indent + line
    self.directive.result.append(self.indent + line, source, *lineno)

Теперь Autodoc Prints сгенерировал RST на STDOUT во время работы, и вы можете просто перенаправить или скопировать его в другом месте.

Answer 2

Bonkey Patching Autodoc Так он работает без необходимости редактировать что-либо:

import sphinx.ext.autodoc
rst = []
def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    rst.append(line)
    self.directive.result.append(self.indent + line, source, *lineno)
sphinx.ext.autodoc.Documenter.add_line = add_line
try:
    sphinx.main(['sphinx-build', '-b', 'html', '-d', '_build/doctrees', '.', '_build/html'])
except SystemExit:
    with file('doc.rst', 'w') as f:
        for line in rst:
            print >>f, line

Answer 3

Насколько я знаю, нет автоматических инструментов для этого. Поэтому мой подход будет написать небольшой сценарий, который читает соответствующие модули (на основе SPHINC.ext.autodoc) и бросает строки дока в файл (отформатирован соответствующим образом).