Readthedocs.org: Suporte a documentos de API gerados automaticamente

fwiw Eu também ficaria feliz se o RTD apenas me permitisse especificar meu próprio processo de compilação, para que não fosse especificamente para suporte de código fixo para sphinx-apidoc . Embora isso também possa ser difícil de permitir de maneira segura.

Também estou tentando usar sphinx-apidoc para minha documentação. Eu uso um tox -e docs para gerar meus documentos

+1 nisso... tenho certeza, mesmo documentando isso no procedimento de liberação, que vou esquecer de gerar os apidocs e enviá-los...

Atualmente estamos desenvolvendo um novo sistema de compilação. E suponho que poderíamos integrar isso de alguma forma. No entanto, ainda não está lá, então presumo que não teremos uma correção para isso nas próximas semanas, mas mais em termos de meses.

+1

Adicionar esse suporte seria incrível e reduziria significativamente o atrito associado à manutenção da documentação atualizada. Se sphinx-apidoc fosse suportado em readthedocs, um desenvolvedor nem precisaria da cadeia de ferramentas sphinx instalada localmente se não quisesse; sua única responsabilidade seria manter as docstrings atualizadas.

+1

:+1:

+1

+1

Para sua informação, você pode contornar isso adicionando algo como o seguinte ao arquivo conf.py do seu projeto:

def run_apidoc(_):
    modules = ['a_list_of',
               'python_module_directories',
               'in_your_project']
    for module in modules:
        cur_dir = os.path.abspath(os.path.dirname(__file__))
        output_path = os.path.join(cur_dir, module, 'doc')
        cmd_path = 'sphinx-apidoc'
        if hasattr(sys, 'real_prefix'):  # Check to see if we are in a virtualenv
            # If we are, assemble the path manually
            cmd_path = os.path.abspath(os.path.join(sys.prefix, 'bin', 'sphinx-apidoc'))
        subprocess.check_call([cmd_path, '-e', '-o', output_path, module, '--force'])

def setup(app):
    app.connect('builder-inited', run_apidoc)

Isso executará sphinx-apidoc durante o evento principal sphinx iniciado pelo construtor. Ele deve funcionar em readthedocs e localmente, permitindo que você gere automaticamente seus documentos de API sem precisar armazenar a saída em seu repositório git. Você pode até mesmo cruzar sua documentação manual com essas referências de API.

Outra solução que não envolve chamar diretamente um subprocesso é usar o seguinte em conf.py:

from sphinx.apidoc import main
main(['-e', '-o', ...])

ao invés de

subprocess.check_call([cmd_path, '-e', '-o', output_path, module, '--force'])

Isso resolveu um dos problemas que tive foi com nomes de caminho longos que são restritos em readthedocs.

@alyjak @Maxyme Obrigado. E isso funciona para mim.

def run_apidoc(_):
    from sphinx.apidoc import main
    import os
    import sys
    sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
    cur_dir = os.path.abspath(os.path.dirname(__file__))
    module = '.'
    output_path = os.path.join(cur_dir, 'source')
    # main(['-e', '-o', output_path, module, '--force'])

def setup(app):
    app.connect('builder-inited', run_apidoc)

@BowenFu

Obrigado! Para que seu código funcione, no entanto, você precisaria descomentar a linha main . Não menos importante, achei isso incompatível com a estrutura de diretórios que costumo ver, onde os arquivos de origem .rst são todos colocados no diretório de documentação (onde config.py também está localizado). O que funcionou para mim foi:

def run_apidoc(_):
    from sphinx.apidoc import main
    import os
    import sys
    sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
    cur_dir = os.path.abspath(os.path.dirname(__file__))
    module = os.path.join(cur_dir,"..","labbookdb")
    main(['-e', '-o', cur_dir, module, '--force'])

def setup(app):
    app.connect('builder-inited', run_apidoc)

Dois comentários sobre o código do @TheChymera , que funciona muito bem e que estou usando agora:

• Você precisará substituir labbookdb pelo nome do seu módulo
• Como a análise de opções começa com o segundo item da lista, -e não é considerado; se você quiser uma página separada por módulo, precisará adicionar None à lista passada para main .

Caso contrário, uma boa solução para o problema de automatizar as atualizações de documentos da API. Obrigado!!

Não tenho certeza se esse é um recurso que implementaremos diretamente no RTD. Ter a solução acima em nossos documentos seria um grande passo! Temos conteúdo semelhante em docs/guides .

Se implementássemos isso em qualquer lugar, acho que poderíamos implementar isso em nossa configuração YAML.

Desde a última versão, o comportamento é o mesmo da compilação do documento local, conforme esperado. Então, eu removi a solução alternativa feita em março.

Obrigado pela correção.

@Guts isso significa que você acabou de adicionar a extensão e funciona como esperado? Podemos encerrar esse assunto então?

Além disso, talvez você queira usar https://github.com/rtfd/sphinx-autoapi

@Guts isso significa que você acabou de adicionar a extensão e funciona como esperado? Podemos encerrar esse assunto então?

sim. Eu removi a solução alternativa e funciona. Então eu acho que funciona como esperado. Para encerrar a questão, talvez devêssemos esperar pelo feedback do autor? cc @radix

Além disso, talvez você queira usar https://github.com/rtfd/sphinx-autoapi

Eu realmente não testei https://github.com/rtfd/sphinx-autoapi porque diz Python 2 only ( Python (2 only -- Epydoc doesn't support Python 3) ) e não tenho muito tempo para tentar e entender outra extensão Sphinx (Eu não sou um especialista em doc, então isso exige que eu realmente mergulhe).

Obrigado por relatar, fecharei isso em alguns dias se o autor original não responder ou se mais alguém estiver tendo esse problema :)

sim, vá em frente e feche-o se você tiver uma resolução, não terei a chance de verificá-lo em breve. Muito obrigado!

Ok, estou encerrando, por favor, avise-nos se você tiver o problema novamente ou se a solução funcionar para você também

Eu tenho usado a correção @TheChymera com grande sucesso até agora, mas tenho que comentar quando quero construir os documentos localmente.

A atualização do @Guts significa que posso descartar essa correção, adicionar extensions = ['autoapi.extension'] no meu conf.py e ele será executado localmente e no RTD?

Edit: Eu não percebi na época, mas autoapi e sphinx-apidoc são bibliotecas muito diferentes com diferentes métodos de análise. A saída pode ser ligeiramente diferente.

A atualização do @Guts significa que posso descartar essa correção, adicionar extensions = ['autoapi.extension'] no meu conf.py e ele será executado localmente e no RTD?

Acho que sim, se você precisar executar o código condicionalmente, poderá ver https://docs.readthedocs.io/en/latest/faq.html#how -do-i-change-behavior-for-read-the-docs

A atualização do @Guts significa que posso descartar essa correção, adicionar extensions = ['autoapi.extension'] no meu conf.py e ele será executado localmente e no RTD?

Isso é o que significa. Pelo menos, foi isso que eu fiz: uma solução alternativa para lidar com envs de compilação local/RTD e, em seguida, removê-lo com a atualização do RTD.

O Sphinx 1.6 a 1.7 quebrou algumas coisas nas quais a solução alternativa acima mencionada dependia. Uma versão compatível com Sphinx 1.6 e 1.7+ está incluída abaixo.

def run_apidoc(_):
    ignore_paths = [
        ...
    ]

    argv = [
        "-f",
        "-T",
        "-e",
        "-M",
        "-o", ".",
        ".."
    ] + ignore_paths

    try:
        # Sphinx 1.7+
        from sphinx.ext import apidoc
        apidoc.main(argv)
    except ImportError:
        # Sphinx 1.6 (and earlier)
        from sphinx import apidoc
        argv.insert(0, apidoc.__file__)
        apidoc.main(argv)


def setup(app):
    app.connect('builder-inited', run_apidoc)

Parece que há algum trabalho em andamento para adicionar a geração automática de documentos de API ao Sphinx.

refex: https://github.com/sphinx-doc/sphinx/pull/4101

Parece que há algum trabalho em andamento para adicionar a geração automática de documentos de API ao Sphinx.

refex: sphinx-doc/sphinx#4101

Isso também é suportado fora da árvore usando a extensão sphinxcontrib.apidoc . Isso é usado extensivamente na comunidade OpenStack e funciona muito bem para nossos propósitos.

Com Sphinx 3.1.1 eu precisava importar
from sphinx.ext.apidoc import main
ao invés de
from sphinx.apidoc import main