FAQ do Sphinx¶

Essa é a lista de Perguntas Frequentes sobre Sphinx. Sinta-se livre para sugerir novas entradas!

Como eu faço…¶

… para criar arquivos PDF sem LaTeX?: rinohtype fornece um construtor de PDF que pode ser usado como um substituto drop-in para o construtor de LaTeX.
… obter seções numeradas?: Elas são automáticas na saída LaTeX; para HTML, use a opção :numbered: para a diretiva toctree onde é desejado o início da numeração.
… configurar a aparência dos arquivos HTML?: Use temas, veja HTML theming.
… adicionar inclusões ou substituições globais?: Adicione-as no valor de configuração rst_prolog ou rst_epilog.
… exibir toda uma árvore de TOC na barra lateral?: Use o chamável toctree em um modelo de layout personalizado, provavelmente no bloco sidebartoc.
… escrever minha própria extensão?: Veja os Tutoriais.
… converter de meus documentos existentes usando a marcação MoinMoin?: A maneira mais fácil é converter para xhtml e, em seguida, converter xhtml para reStructuredText. Você ainda precisará marcar classes e coisas assim, mas os títulos e exemplos de código vêm de forma limpa.

Para muitas outras extensões e outras contribuições, consulte o repositório sphinx-contrib.

Usar Sphinx com…¶

Read the Docs

Read the Docs é um serviço de hospedagem de documentação baseado no Sphinx. Eles hospedarão a documentação do sphinx, junto com o suporte de uma série de outros recursos, incluindo suporte de versão, geração de PDF e muito mais. O guia Primeiros passos é um bom lugar para começar.

Epydoc

Existe uma extensão de terceiros que fornece um papel de api que faz referência aos documentos da API do Epydoc para um determinado identificador.

Doxygen

Michael Jones desenvolveu uma ponte reStructuredText/Sphinx para doxygen chamada breathe.

SCons

Glenn Hutchings escreveu um script de construção de SCons para construir a documentação do Sphinx; está hospedado aqui: https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html

PyPI

Jannis Leidel escreveu um comando setuptools que carrega automaticamente a documentação Sphinx para a área de documentação do pacote PyPI em https://pythonhosted.org/.

GitHub Pages

Adicione sphinx.ext.githubpages ao seu projeto. Ele permite que você publique seu documento nas páginas do GitHub. Ele gera arquivos auxiliares para GitHub Pages na construção de documentos HTML automaticamente.

MediaWiki

Veja sphinx-wiki, um projeto de Kevin Dunn.

Google Analytics

Você pode usar um modelo layout.html personalizado, como este:

{% extends "!layout.html" %}

{%- block extrahead %}
{{ super() }}
<script>
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'XXX account number XXX']);
  _gaq.push(['_trackPageview']);
</script>
{% endblock %}

{% block footer %}
{{ super() }}
<div class="footer">This page uses <a href="https://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script>
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'https://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>
{% endblock %}

Pesquisa Google

Para substituir a função de pesquisa integrada do Sphinx pela Pesquisa Google, proceda da seguinte forma:

Acesse https://cse.google.com/cse/all para criar o trecho de código de Pesquisa Google.

Copie o trecho de código e cole-o em _templates/searchbox.html em seu projeto Sphinx:

<div>
   <h3>{{ _('Quick search') }}</h3>
   <script>
      (function() {
         var cx = '......';
         var gcse = document.createElement('script');
         gcse.async = true;
         gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
         var s = document.getElementsByTagName('script')[0];
         s.parentNode.insertBefore(gcse, s);
      })();
   </script>
  <gcse:search></gcse:search>
</div>

Adicione searchbox.html ao valor de configuração html_sidebars.

Sphinx vs. Docutils¶

De forma resumida, docutils converte reStructuredText em vários formatos de saída. O Sphinx se baseia no docutils para permitir a construção de corpos de documentação com referência cruzada e indexados.

docutils é um sistema de processamento de texto para converter documentação de texto simples em outros formatos mais ricos. Conforme observado na documentação do docutils, docutils usa leitores para ler um documento, analisadores para analisar formatos de texto simples em uma representação de árvore interna composta de diferentes tipos de nós e escritores para gerar este árvore em vários formatos de documento. docutils fornece analisadores para um formato de texto simples – reStructuredText – embora outros analisadores fora da árvore tenham sido implementados incluindo o analisador Markdown do Sphinx. Por outro lado, ele fornece escritores para muitos formatos diferentes, incluindo HTML, LaTeX, páginas man, Open Document Format e XML.

docutils expõe todas as suas funcionalidades através de uma variedade de ferramentas front-end, como rst2html, rst2odt e rst2xml. Porém, crucialmente, todas essas ferramentas, e os próprios docutils, estão relacionados a documentos individuais. Eles não oferecem suporte a conceitos como referência cruzada, indexação de documentos ou a construção de uma hierarquia de documentos (normalmente manifestando-se em um índice analítico).

O Sphinx se baseia em docutils, aproveitando os leitores e analisadores de docutils e fornecendo seus próprios Construtores. Como resultado, o Sphinx envolve alguns dos escritores fornecidos pelos docutils. Isso permite que o Sphinx forneça muitos recursos que simplesmente não seriam possíveis com docutils, como os descritos acima.

Informações de epub¶

A lista a seguir fornece algumas dicas para a criação de arquivos epub:

Divida o texto em vários arquivos. Quanto mais longos são os arquivos HTML individuais, mais tempo leva para o leitor de e-books processá-los. Em casos extremos, a renderização pode levar até um minuto.
Tente minimizar a marcação. Isso também compensa no tempo de renderização.
Para alguns leitores, você pode usar fontes incorporadas ou externas usando a diretiva CSS @font-face. Isso é extremamente útil para listagens de código que geralmente são cortadas na margem direita. A fonte Courier padrão (ou variante) é bastante ampla e você só pode exibir até 60 caracteres em uma linha. Se você substituí-la por uma fonte mais estreita, pode obter mais caracteres em uma linha. Você pode até usar FontForge e criar variantes estreitas de alguma fonte livre. No meu caso, recebo até 70 caracteres em uma linha.

Você pode ter que experimentar um pouco até obter resultados razoáveis.
Teste os epubs criados. Você pode usar várias alternativas. Os que conheço são Epubcheck, Calibre, FBreader (embora não renderize o CSS) e Bookworm. Para Bookworm, você pode baixar o código-fonte em https://code.google.com/archive/p/threepress e executar seu próprio servidor local.
Divs flutuantes grandes não são exibidos corretamente. Se eles cobrirem mais de uma página, o div será mostrado apenas na primeira página. Nesse caso, você pode copiar o epub.css do diretório sphinx/themes/epub/static/ para seu diretório local _static/ e remover as configurações de float.
Os arquivos inseridos fora da diretiva toctree devem ser incluídos manualmente. Isso às vezes se aplica a apêndices, por exemplo o glossário ou os índices. Você pode adicioná-los com a opção epub_post_files.
O tratamento da página de rosto do epub difere do procedimento do reStructuredText que resolve automaticamente os caminhos das imagens e as coloca no diretório _images. Para a página de rosto do epub, coloque a imagem no diretório html_static_path e faça referência a ela com seu caminho completo na opção de configuração epub_cover.
O comando kindlegen pode converter do arquivo resultante epub3 para o arquivo .mobi para Kindle. Você pode obter yourdoc.mobi em _build/epub após o seguinte comando:
```
$ make epub
$ kindlegen _build/epub/yourdoc.epub
```
O comando kindlegen não aceita documentos que tenham títulos de seção em torno da diretiva toctree:
```
Section Title
=============

.. toctree::

   subdocument

Section After Toc Tree
======================
```
kindlegen assume que todos os documentos estejam em ordem, mas o documento resultante tem uma ordem complicada para o kindlegen:
```
``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
```
Se você receber o seguinte erro, corrija a estrutura do seu documento:
```
Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
Error(prcgen):E24001: The table of content could not be built.
```

Informações de Texinfo¶

Existem dois programas principais para ler arquivos Info, info e GNU Emacs. O programa info tem menos recursos, mas está disponível na maioria dos ambientes Unix e pode ser acessado rapidamente do terminal. O Emacs oferece melhor fonte e exibição de cores e suporta ampla personalização (é claro).

Exibindo links¶

Um problema perceptível que você pode encontrar com os arquivos Info gerados é como as referências são exibidas. Se você ler a fonte de um arquivo Info, uma referência a esta seção seria semelhante a:

* note Displaying Links: target-id

No leitor autônomo, info, as referências são exibidas exatamente como aparecem na fonte. Emacs, por outro lado, irá por padrão substituir *note: por see e ocultar o target-id. Por exemplo:

Exibindo links

Pode-se desabilitar a geração das referências em linha em um documento com texinfo_cross_references. Isso torna um arquivo de informação mais legível com o leitor autônomo (info).

O comportamento exato de como o Emacs exibe as referências depende da variável Info-hide-note-extensions. Se definido com o valor de hide, o Emacs irá ocultar a parte *note: e o target-id. Em geral, essa é a melhor maneira de visualizar documentos baseados no Sphinx, pois eles costumam fazer uso frequente de links e não levam essa limitação em consideração. No entanto, a alteração dessa variável afeta a forma como todos os documentos Info são exibidos e a maioria leva esse comportamento em consideração.

Se você deseja que o Emacs exiba os arquivos Info produzidos pelo Sphinx usando o valor hide para Info-hide-note-extensions e o valor padrão para todos os outros arquivos Info, tente adicionar o seguinte código Emacs Lisp ao seu arquivo de inicialização, ~/.emacs.d/init.el.

(defadvice info-insert-file-contents (after
                                      sphinx-info-insert-file-contents
                                      activate)
  "Hack to make `Info-hide-note-references' buffer-local and
automatically set to `hide' iff it can be determined that this file
was created from a Texinfo file generated by Docutils or Sphinx."
  (set (make-local-variable 'Info-hide-note-references)
       (default-value 'Info-hide-note-references))
  (save-excursion
    (save-restriction
      (widen) (goto-char (point-min))
      (when (re-search-forward
             "^Generated by \\(Sphinx\\|Docutils\\)"
             (save-excursion (search-forward "\x1f" nil t)) t)
        (set (make-local-variable 'Info-hide-note-references)
             'hide)))))

Notas¶

As notas a seguir podem ser úteis se você deseja criar arquivos Texinfo:

Cada seção corresponde a um node diferente no arquivo Info.
Dois pontos (:) não podem ser escapados apropriadamente em entradas de menu e refexs. Eles serão substituídos por ponto-e-vírgulas (;).
Links para arquivos Info externos podem ser criados usando o esquema URI oficial do info. Por exemplo:
```
info:Texinfo#makeinfo_options
```