sphinx-apidoc

Sinopse

sphinx-apidoc [OPÇÕES] -o <CAMINHO_SAÍDA> <CAMINHO_MÓDULO> [PADRÃO_EXCLUSÃO …]

Descrição

sphinx-apidoc é uma ferramenta para geração automática de código-fonte Sphinx que, usando a extensão autodoc, documenta um pacote inteiro no estilo de outras ferramentas de documentação automática da API.

MODULE_PATH é o path para um pacote do Python para documentar, e OUTPUT_PATH é o diretório onde as fontes geradas são colocadas. Quaisquer EXCLUDE_PATTERNs são dados do arquivo fnmatch-style e/ou padrões de diretório que serão excluídos da geração.

Aviso

sphinx-apidoc gera arquivos de origem que usam sphinx.ext.autodoc para documentar todos os módulos encontrados. Se algum módulo tiver efeitos colaterais na importação, eles serão executados pelo autodoc quando sphinx-build for executada.

Se os scripts do seu documento, (diferentemente de módulos de biblioteca), certificar-se que suas rotinas main estejam protegidas por um if __name__ == '__main__' condição.

Opções

-o <OUTPUT_PATH>

Diretório para colocar os arquivos de saída. Se não existir, será criado.

-q

Não emitir saída nenhuma na saída padrão, só gravar avisos de erros na saída padrão de erros.

-f, --force

Forçar a sobrescrita de quaisquer arquivos gerados existentes.

-l, --follow-links

Segue links simbólicos. O padrão é False.

-n, --dry-run

Não cria nem remove quaisquer arquivos.

-s <suffix>

Sufixo para os arquivos de origem gerados. O padrão é rst.

-d <MAXDEPTH>

Profundidade máxima para o arquivo da tabela de conteúdo gerada. O padrão é 4.

--tocfile

Nome de arquivo para um arquivo de índice. O padrão é modules.

-T, --no-toc

Não crie um arquivo de índice. Ignorado quando --full é fornecido.

--remove-old

Remove os arquivos existentes no diretório de saída que não são mais criados. Não é compatível com --full.

-F, --full

Gere um projeto completo do Sphinx (conf.py, Makefile etc.) usando o mesmo mecanismo que sphinx-quickstart.

-e, --separate

Coloque documentação para cada módulo em sua própria página.

Adicionado na versão 1.2.

-E, --no-headings

Não crie cabeçalhos para os módulos/pacotes. Isso é útil, por exemplo, quando as docstrings já contêm títulos.

-P, --private

Inclua módulos _private.

Adicionado na versão 1.2.

--implicit-namespaces

Sem essa opção, sphinx-apidoc pesquisa em sys.path por pacotes Python contendo arquivos __init__.py ou módulos Python de arquivo único.

Esta opção usa espaços de nomes implícitos da PEP 420 que permitem caminhos de layout como foo/bar/module.py ou foo/bar/baz/__init__.py (observe que bar e foo são espaços de nomes, não módulos).

-M, --module-first

Coloque a documentação do módulo antes da documentação do submódulo.

Essas opções são usadas quando --full é especificado:

-a

Anexa ao final module_path em sys.path.

-H <project>

Configura o nome do projeto para ser gravado nos arquivos gerados (ver project).

-A <author>

Configura nome(s) do autor(es) para gerar arquivos (ver copyright).

-V <version>

Configura versão do projeto a ser colocada nos arquivos gerados (ver version).

-R <release>

Define o nome do release do projeto para ser colocado nos arquivos gerados (ver release).

Projeto Modelo

Adicionado na versão 2.2: Opções de modelagem de projeto para sphinx-apidoc

-t, --templatedir=TEMPLATEDIR

Diretório de modelo para arquivos de modelo. Você pode modificar os modelos de arquivos de projeto sphinx gerados pelo apidoc. Os seguintes arquivos de modelo Jinja2 são permitidos:

  • module.rst.jinja

  • package.rst.jinja

  • toc.rst.jinja

  • root_doc.rst.jinja

  • conf.py.jinja

  • Makefile.jinja

  • Makefile.new.jinja

  • make.bat.jinja

  • make.bat.new.jinja

Em detalhes, consulte os arquivos de modelo do sistema que a Sphinx fornece. (sphinx/templates/apidoc e sphinx/templates/quickstart)

Ambiente de Desenvolvimento

SPHINX_APIDOC_OPTIONS

Uma lista separada por vírgula de opção para anexar às diretivas automodule geradas. O padrão é members,undoc-members,show-inheritance.

Ver também

sphinx-build(1), sphinx-autogen(1)