Fazer esfinge gerar documentação da primeira classe a partir de pydoc

Question

Atualmente estou migrando toda a documentação existente (incompleta) para Esfinge.

O problema é que a documentação usa Python Docstrings (O módulo está escrito em C, mas provavelmente não importa) e a documentação da classe deve ser convertida em uma forma utilizável para a Esfinge.

Há sphinx.ext.autodoc, mas ele automaticamente coloca os documentos atuais no documento. Eu quero gerar um arquivo de origem em (RST) com base no DocStrings atuais, que eu poderia editar e melhorar manualmente.

Como você transformaria o DocStrings em primeiro para a Esfinge?

Answer 1

O Autodoc gera primeiro apenas não há uma maneira oficial de tirá -lo. O hack mais fácil de obtê -lo foi mudando sphinx.ext.autodoc.Documenter.add_line Método para me emitir a linha que recebe.

Como tudo o que quero é uma vez a migração, a saída para o stdout é boa o suficiente para mim:

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)

Agora, as impressões do AutoDoc geraram o RST no stdout enquanto estiver em execução e você pode simplesmente redirecioná -lo ou copiá -lo para outro lugar.

Answer 2

Monkey Patching Autodoc, para que funcione sem precisar editar nada:

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

Até onde eu sei, não há ferramentas automatizadas para fazer isso. Minha abordagem seria, portanto, escrever um pequeno script que lê módulos relevantes (baseados em sphinc.ext.autodoc) e lança strings de documentos em um arquivo (formatado adequadamente).