Заставить Sphinx генерировать документацию класса RST из pydoc - PullRequest
Новая
       37

Заставить Sphinx генерировать документацию класса RST из pydoc

7 голосов
/ 19 апреля 2010

Я сейчас перевожу всю существующую (неполную) документацию в Sphinx .

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

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

Как бы вы преобразовали строки документации в RST для Сфинкса?

Ответы [ 3 ]

13 голосов
/ 26 апреля 2010

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

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

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 печатает сгенерированный RST на стандартный вывод во время работы, и вы можете просто перенаправить или скопировать его в другом месте.

2 голосов
/ 27 июля 2015

Обезьяна исправляет 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
0 голосов
/ 25 апреля 2010

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

...