Sphinx

Quando criado, pela primeira vez, o seu objectivo principal era servir como um gerador de documentação para Python 's código próprio.
Desde então, o projeto alcançou status cult no mundo do desenvolvimento, sendo uma das influências mais referenciados em geradores automáticos de documentação mais ao redor, independentemente do idioma.
Hoje, além de apenas Python, Sphinx pode também ser usado com C e C ++ código também.

O que é novo nesta versão:

• Adicionar directivas de conveniência e funções para o C ++ domínio: directiva `` cpp: var`` como alias para `` cpp: member``, papel ``: cpp: var`` como alias para ``: cpp: member `` e `papel any` para referência cruzada para qualquer declaraction C ++.
• A: confval: `valor de configuração source_suffix` agora pode ser uma lista de vários sufixos
.
• Adicione a capacidade de especificar analisadores de origem por sufixo de origem com o: confval:. `Valor de configuração source_parsers`
• Um novo construtor, AppleHelpBuilder, foi acrescentado que constrói Apple Help Books.

O que é novo na versão 1.2.3 / 1.3b3:

• Adicionado `` sphinx.version_info`` tupla para a verificação programático da versão Esfinge.

O que é novo na versão 1.1.3:

• Corrigida a falha com algumas configurações de: confval:. `Modindex_common_prefix`
• manipulação de `` e `` -D`` opções -A`` fixo em Python 3.
• Reconhecido e alertar sobre toctrees circulares, em vez de correr em erros de recursão.
• Restaurar a compatibilidade com docutils tronco.
• ligações de entrada de índice fixos HTMLHELP novamente.
• Fixed inheritance_diagram levantando erros de atributos em builtins.
• A falha foi corrigida quando colocando comentários ou termos isolados em um glossário.
• ajuda HTML Fixo mapeamento de linguagem / codificação para todos Sphinx idiomas suportados.

O que é novo na versão 1.1:

• Características acrescentou:
• Adicionado suporte 3.x do Python.
• Novos construtores e subsistema.
• mudanças incompatíveis:
• A: primeira: dir: `py: directiva module` não sai seu` `valor da opção platform`` mais. (Foi a única coisa que a directiva teve saída, e, portanto, bastante inconsistente.)
• eliminou o apoio a versões antigas de dependência.
• Novos idiomas:
• localidade sueca Adicionado.
• locale iraniano acrescentou.
• locale letão Adicionado.
• Adicionado locale Nepali.
• Adicionado localidade coreano.
• locale estoniano Adicionado.

O que é novo na versão 1.0.8:

• tracebacks correção para AttributeErrors em geração AutoSummary.
• Corrija o `` abbr`` papel quando a sigla tem novas linhas nele.
• Corrija as ligações a resultados de pesquisa com tipos de objetos personalizados.
• números de linha Fix relatados em avisos sobre referências indefinidas.
• C ++ definições de matriz Fix e argumentos de modelo que não são do tipo nomes.
• Permitir que as notas de rodapé em cabeçalhos de seção na saída LaTeX.
• Permitir palavras-chave para ser ligada via intersphinx.
• Permitir caracteres Unicode na lista de nomes de token de produção.
• Adicione os visitantes do manequim para nós Graphviz para o texto eo homem.
• Fix arquivo de imagem a duplicação bug.
• Fix análise de várias assinaturas em C ++ domínio.
• Ignorar arquivos de bloqueio Emacs quando se olha para os arquivos de origem.
• Permitir extensão .pyw para módulos importáveis ​​em autodoc.
• Use `` $ (MAKE) `` no gerado-quickstart Makefiles.
• Faça largura da caixa de pesquisa da barra lateral consistente em browsers.
• espaçamento Fix de figuras centradas na saída HTML.
• com segurança codificar mensagens SphinxError quando imprimi-los para sys.stderr.
• erro de saída Fix LaTeX com um documento sem seções, mas uma meta link.
• corretamente tratar embutidos descritores de método como métodos em autodoc.
• Parar monkeypatching o módulo TextWrap Python.
• ViewCode agora funciona corretamente com arquivos de origem que possuem codificação de não-ASCII.
• Respeite a opção bandeira `` noindex`` em py:. Directivas módulo
• IndexErrors Fix incluindo quando não existente com linhas: primeiro: dir: `literalinclude`.

Cordas
• função personalizada Respeito / parâmetro método de separação.
• incompatibilidade Fix JS com jQuery & gt;. = 1,5
• Corrija codificação duplo feito ao escrever HTMLHelp .hhk arquivos.
• Não aplicar SmartyPants em blocos de literais analisados.
• C ++ domínio agora suporta definições de matriz.

O que é novo na versão 1.0.6:

• Fix traceback no domínio Python para alvos de referência cruzada vazias.
• Resolver problemas de exibição bloco literais em navegadores Chrome.
• Suporte a classificação de uma gama limitada de caracteres acentuados no índice geral e glossário.
• Tente descodificar `` -D`` e `` linha de comando argumentos -A`` com a codificação preferida do local.
• Observe: confval:. `Locale_dirs` quando se olha para o arquivo traduções JS
• Adicione o código especial para melhorar o suporte de documentos japoneses no construtor LaTeX.
• Regressão de # 77: Se houver apenas um parâmetro dado com ``: param:. `` Marcação, a lista de marcadores agora é suprimida novamente
• Corrija faltando quebras de parágrafo na saída LaTeX em determinadas situações.
• Emitir o evento `` autodoc-processo-docstring`` mesmo para objetos sem uma docstring para que ele possa adicionar conteúdo.
• No construtor LaTeX, não só os blocos literais requerem um tratamento tabela diferente, mas também alguns outros elementos de bloco de lista do tipo.
• tracebacks corrigir na extensão ViewCode para objetos Python que não tem uma assinatura válida.
• Corrija reportagens estranhas de números de linhas para avisos gerados a partir de docstrings incluiu-AutoDoc, devido a um comportamento diferente dependendo da versão docutils.
• Várias correções para o domínio C ++.

O que é novo na versão 1.0.5:

• Adicione os estilos CSS exigidos pela docutils 0,7 para imagens e figuras alinhadas.
• No Makefile gerado pela saída LaTeX, não exclua arquivos pdf no limpo; eles podem ser necessárias imagens.
• saída Fix LaTeX gerados para blocos de linha.
• Permita `` .pyw`` como uma extensão de arquivo fonte.

O que é novo na versão 1.0.4:

• inventários intersphinx abertas em modo binário no Windows, desde a versão 2 contém dados comprimidos zlib-.
• Permitir que dá URIs não-locais para arquivos JavaScript, por exemplo, na extensão JSMath.
• Fix traceback quando `` intersphinx_mapping`` está vazio.

O que é novo na versão 1.0.3:

• Corrija interno vs. distinção link externo para ligações provenientes de um docutils mesa-de-conteúdo.
• Corrija a opção `` maxdepth`` para o `` toctree () `` modelo que pode ser chamado quando usado com `` colapso = True``.
• Fix acidente analisar Python listas de argumentos contendo suportes em strings literais.
• regressão Fix ao construir docs LaTeX com figuras que não têm legendas.
• diagramas de herança correção para classes que não estão picklable.
• Apresente cor de fundo separado para o botão da barra lateral colapso, tornando-o mais fácil de ver.
• Corrigir pequenos erros de layout em vários temas internos.

O que é novo na versão 1.0.2:

• Resolver referências cruzadas para objetos de tipos adicionados pelo: func:. `~ Função API .Sphinx.add_object_type`
• Fix manipulação de tipos de campo doc para diferentes tipos de directiva.
• Permitir quebra assinaturas longos, continuando com novas linhas escapou-folga.
• Corrija styling indesejado de referências domínio C (por causa de um choque namespace com estilos pygments).
• Permitir referências a PEPs e RFCs com âncoras explícitas.
• referências Fix látex para figuras.
• Ao fazer uma pesquisa não-exato, fósforo apenas o tipo de dado de objeto.
• Aplicar pesquisa não-exata para alvos de referência Python com `` .name`` para módulos também.
• Fix acidente quando duplicar um parâmetro em uma lista de informações de campo.
• Corrija definir o papel padrão para aquele fornecido pela extensão `` oldcmarkup``.
• Fix acidente quando json-py está instalado, que fornece um módulo `` json`` mas é incompatível com simplejson.
• manipulação Fix alvo de nomeação em intersphinx.
• remoção Fix de ``! `` Para todas as funções de referência cruzada.

O que é novo na versão 1.0.1:

• Resolver nomes de destino para objetos de domínio gerados repouso; eles não estão no mesmo namespace.
• Adicionar idioma bengali.
• Corrigir um erro ao analisar nomes de objetos JavaScript.
• Corrija prédio com SingleHTMLBuilder quando não há toctree.
• nomes de exibição Fix para objetos vinculados pelo intersphinx com metas explícitas.
• Corrija a construção com o construtor JSON.
• hyperrefs Fix em descrições de objetos para LaTeX.

O que é novo na versão 1.0:

• Geral:
• Adicionado um modo de "detalhista" que emite avisos para todas as referências ausentes. Ele é ativado pela opção:: `opção de linha de comando ou o -n`: confval:.` Valor de configuração nitpicky`
• Adicionado `` alvo latexpdf`` em quickstart Makefile.
• Markup:
• A: primeira: papel: `menuselection` e: primeiro: papel:.` Papéis guilabel` agora suporta aceleradores ampersand
• New sintaxe doc campo mais compacto é agora reconhecida: ``: nome do tipo de param:. Description``
• Adicionado `` opção de guia width`` a: primeiro: dir:. `Directiva literalinclude`
• Adicionado `` opção titlesonly`` a: primeiro: dir:. `Directiva toctree`
• Adicionado o `` e `` prepend`` opções append`` à: primeira: dir:. `Directiva literalinclude`
• Todos docinfo metadados é agora colocado no metadados do documento, e não apenas o autor.
• A: primeira: papel: `papel ref` agora também pode fazer referência a tabelas por subtítulo
.
• A: primeira: dir:. `Directiva include` agora suporta caminhos absolutos, que são interpretadas como em relação ao diretório de origem
• No domínio Python, referências como ``: func: `. .name``` Agora olhar para os nomes combinando com qualquer prefixo se nenhuma correspondência direta é encontrada
• Configuração:
• Adicionado: confval:. `Valor de configuração rst_prolog`
• Adicionado: confval:. `Valor de configuração html_secnumber_suffix` para controlar seção formato de numeração
• Adicionado: confval:. `Valor de configuração html_compact_lists` para controlar listas de compactos 'dos ​​docutils apresentam
• A: confval: `valor de configuração html_sidebars` agora pode conter padrões como chaves, e os valores podem ser listas que selecionam explicitamente quais modelos da barra lateral deve ser processado. Isso significa que o conteúdo da barra lateral embutidas podem ser incluídos apenas selectivamente.
• : confval:. `Agora html_static_path` pode conter entradas de arquivo individuais
• O novo valor de configuração universal: confval: `exclude_patterns` faz o velho: confval:` unused_docs`,: confval: `exclude_trees` e: confval:.` Exclude_dirnames` obsoleto
• Adicionado: confval:. `Valor de configuração html_output_encoding`
• Adicionado o: confval: `valor de configuração latex_docclass` e fez a opção documentclass" twoside "substituível por" oneside "
.
• Adicionado o: confval:. `Valor de configuração trim_doctest_flags`, o que é verdade por padrão
• Adicionado: confval:. `Valor de configuração html_show_copyright`
• Adicionado: confval: `latex_show_pagerefs` e: confval:.` Valores de configuração latex_show_urls`
• O comportamento de: confval: `html_file_suffix` mudou um pouco: a cadeia vazia agora significa" nenhum sufixo "em vez de" sufixo padrão ", use` `None`` para" sufixo padrão "
.
• Novos construtores:
• Adicionado um construtor para o formato ePub.
• Adicionado um construtor de páginas de manual.
• Adicionado um construtor HTML de arquivo único.
• saída HTML:

Papéis
• Inline agora obter uma classe CSS com seu nome, permitindo estilos de personalizar sua aparência. Funções específicas de domínio obter duas classes, `` e `` domain`` domínio de rolename``.
• Referências agora obter a classe `` internal`` se eles são internos para todo o projeto, ao contrário de interna para a página atual.
• Referências externas podem ser decorados de forma diferente com a nova opção de tema `` externalrefs`` para o tema padrão.
• No tema padrão, a barra lateral pode experimentalmente agora ser feita desmontável usando a nova opção de tema `` collapsiblesidebar``.
• Toctrees estão agora envolto em um `` tag div`` com a classe `` toctree-wrapper`` na saída HTML.
• A: data:. `Toctree` pode ser chamada em modelos agora tem um argumento` `palavra-chave maxdepth`` para controlar a profundidade da árvore gerada
• A: data:. `Toctree` pode ser chamada em modelos agora aceita um argumento` `palavra-chave titles_only``
• Adicionado `` bloco htmltitle`` no modelo de layout.
• Na busca JavaScript, permitirá à procura de nomes de objetos, incluindo o nome do módulo, como `` sys.argv``.
• Adicionado `` haiku`` novo tema, inspirado no guia do usuário Haiku OS.
• Adicionado novo tema `` nature``.
• Adicionado `` agogo`` novo tema, criado por Andi Albrecht.
• Adicionado `` scrolls`` novo tema, criado por Armin Ronacher.
• Adicionado uma opção `` visitedlinkcolor`` tema para o tema padrão.
• melhor capacidade de resposta da página de pesquisa, carregando thesearch índice de forma assíncrona.
• API de extensão:
• Adicionado: evento:. `Html-collect-pages`
• Adicionado: confval: `valor de configuração e needs_sphinx`: meth:.` ~ Método API aplicação sphinx.application.Sphinx.require_sphinx`
• Adicionado: meth:. ~ Método `API aplicação sphinx.application.Sphinx.add_stylesheet`
• Extensões:
• Adicionado o: mod: `~ extensão sphinx.ext.viewcode`
.
• Adicionado o: mod: `~ extensão sphinx.ext.extlinks`
.
• Adicionado suporte para ordenação fonte de membros em autodoc, com `` autodoc_member_order = 'bysource'``.
• Adicionado: confval:. `Autodoc_default_flags` valor de configuração, que pode ser usado para selecionar sinalizadores padrão para todas as diretrizes AutoDoc
• Adicionado um caminho para intersphinx para se referir a rótulos chamados em outros projetos, e para especificar o projeto que você deseja conectar-se a.
• AutoDoc agora podem documentar instância atributos atribuído em `` métodos __init__``.
• Muitas melhorias e correções para o: mod:. `~ Extensão sphinx.ext.autosummary`, graças à Pauli Virtanen
• A: mod: `~ extensão sphinx.ext.graphviz` pode SVG agora de saída, em vez de imagens PNG, controlada pelo confval:.` Valor de configuração graphviz_output_format`
• Adicionado `` opção alt`` a: primeiro: dir:. `Directivas extensão graphviz`
• Adicionado argumento `` exclude`` para: func:. `.autodoc.between`
• Traduções:
• Adicionado croata tradução, graças a Bojan Mihelac.
• Adicionado tradução turca, graças a Firat Ozgul.
• tradução Adicionado catalão, graças a Pau Fernandez.
• Adicionado tradução para chinês simplificado.
• Adicionado tradução dinamarquesa, graças a Hjorth Larsen.
• Adicionado tradução lituano, graças a Dalius Dobravolskas.

O que é novo na versão 1.0b1:

• Suporte para domínios foi adicionado. Um domínio é um conjunto de diretrizes e funções que descrevem todos os objetos pertencentes juntos, por exemplo, elementos de uma linguagem de programação. Alguns domínios embutidas são fornecidos: - Python - C - C ++ - JavaScript - reStructuredText
• O velho marcação para definir e ligando para directivas C não vai mais funcionar sem ativar a extensão `` oldcmarkup``.
• eliminou o apoio a versões antigas de dependência.
• elementos obsoletos removidos.

O que é novo na versão 0.6.5:

• Em autodoc, corrigir a omissão de alguns membros do módulo explicitamente documentadas utilizando comentários de documentação.
• Fix corte de barra de rolagem lateral com `` opção stickysidebar`` do tema padrão.
• Sempre gerar novas linhas UNIX no Makefile quickstart.
• Corrija correndo com `` -C`` no Windows.
• Em autodoc, permitem personalizar a assinatura de um objeto onde o mecanismo interno falhar.
• saída Fix para listas numeradas com valores de início em LaTeX.
• Faça o `` start-after`` e `` opções de fim de before`` ao trabalho `` directiva literalinclude`` corretamente se não for usado em conjunto.
• geração ligação Fix no construtor LaTeX.

O que é novo na versão 0.6.4:

• Melhorado a manipulação de sequências não Unicode na configuração.
• OSErrors captura ocorre ao chamar graphviz com argumentos que não entende.
• Restaurar a compatibilidade com pygments & gt;. = 1,2
• Corrija escapar de alvos hyperref na saída LaTeX.
• Links Fix gerados pelo ``: doc: ``. Papel para a saída LaTeX
• Recolha TODO nós depois de todo o documento foi lido; isso permite colocar referências de substituição em TODO itens.
• Não ignorar um `` valor explícito de configuração today`` em uma compilação de LaTeX.
• O `` texto alt`` de diagramas de herança é agora muito mais limpas.
• Ignorar imagens em títulos de seção ao gerar links legendas.
• mensagens de exceção apoio na `` blocos testoutput`` da extensão doctest`` ``.
• blocos de linha são denominados corretamente na saída HTML.
• Feito o `` trabalho valor de configuração locale_dirs`` novamente.
• `` valores html_context`` dado na linha de comando via `` -A`` não deve substituir outros valores indicados no conf.py.
• Corrigir um bug que impedia reconstruções incrementais para o `` construtor dirhtml``.
• Corrija a desconfiguração de citações em alguns blocos literais.
• Fix caminho para o índice de pesquisa para o `` construtor dirhtml``.
• Resolver um problema de compatibilidade Jython: fazer a dependência do módulo `` parser`` opcional
.
• Em autodoc, pegar todos os erros que ocorrem na importação módulo, não apenas `` ImportError``.
• Corrija o tratamento de não-dados, mas não de método descritores em autodoc.
• Ao copiar arquivos vezes, ignorar OSErrors levantadas por `` os.utime () ``.

Requisitos :

• pygments 1.2 ou superior
• Jinja 2.3 ou superior
• Docutils 0/7 ou superior