sphinx-apidoc

Sinopse

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

Descrição

sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools.

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

Follow symbolic links. Defaults to False.

-n, --dry-run

Não crie arquivos.

-s <suffix>

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

-d <MAXDEPTH>

Maximum depth for the generated table of contents file. Defaults to 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.

-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

Por padrão, sphinx-apidoc processa busca sys.path para módulos. Python 3.3 introduziu PEP 420 namespaces implicitos que permitem path e estruturas de módulos como foo/bar/module.py ou foo/bar/baz/__init__.py (perceba que bar e foo são namespaces, não modulos).

Interprete os paths recursivamente de acordo com a pep-0420.

-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_t

  • package.rst_t

  • toc.rst_t

  • root_doc.rst_t

  • conf.py_t

  • Makefile_t

  • Makefile.new_t

  • make.bat_t

  • make.bat.new_t

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)