Use Sphinx para criar documentação em vários formatos no CentOS 7

• Pré-requisitos
• Etapa 1: atualizar o sistema
• Etapa 2: Instalar o pip e o Sphinx
• Etapa 3: definir a configuração básica da sua documentação
• Etapa 4: construa a hierarquia para sua documentação
• Etapa 5: criar arquivos de origem especificados acima
• Etapa 6: enviar a versão HTML da sua documentação

O Sphinx é uma ferramenta útil baseada em Python para técnicos e escritores que permite criar facilmente documentação elegante e totalmente funcional em vários formatos. Com o Sphinx, você escreve documentos usando o reStructuredText - uma linguagem de marcação leve - para iniciantes, e pode obter a saída em vários formatos, incluindo HTML, LaTeX, PDF, ePub e outros.

Neste tutorial, abordaremos o processo de instalação e uso Sphinxem uma instância do CentOS 7 x64 na plataforma do Vult.

Pré-requisitos

• Uma instância do CentOS 7 x64.
• Um usuário sudo .

Etapa 1: atualizar o sistema

sudo yum update
sudo shutdown -r now

Etapa 2: Instalar o pip e o Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

Etapa 3: definir a configuração básica da sua documentação

Antes de começar a usar Sphinx, você precisa especificar o diretório de origem no qual Sphinxserá executado e salvar toda a sua documentação. Depois de criar o diretório que pretende usar, você poderá executar o sphinx-quickstartque inicializará Sphinxe criará a configuração básica necessária.

sphinx-quickstart é semelhante a um assistente de configuração que solicitará perguntas que determinam os aspectos do seu projeto.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Etapa 4: construa a hierarquia para sua documentação

Por padrão, o sphinx-quickstartassistente criará vários diretórios e arquivos.

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

Vamos dar uma olhada no arquivo mestre index.rst, que contém a hierarquia da sua documentação; ou seja, a árvore do sumário ou toctree.

Abra-o com um editor de texto:

vi index.rst

Ao revisar o arquivo, você notará uma seção chamada toctree. Se você tiver outros arquivos de origem ( *.rst) para sua documentação, precisará especificá-los na toctreeseção: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

É imperativo:

• Deixe uma linha em branco acima da sua entrada.
• Não use como sufixo seus arquivos de origem .rst.
• Coloque seus arquivos de origem em sua respectiva ordem.
• Use apenas um nome de arquivo por linha.
• Recue seus nomes de arquivos com :maxdepth: 2.

Depois de concluir as modificações, salve o arquivo e saia do editor de texto.

ESC
:!wq

Etapa 5: criar arquivos de origem especificados acima

Os arquivos de origem devem ser criados com nomes que correspondam ao que foi especificado anteriormente index.rst, caso contrário, eles não serão incluídos na saída final.

Todos os arquivos de origem devem ser compatíveis com o reStructuredText markup language. Para mais informações, consulte o reStructuredText Primer .

Etapa 6: enviar a versão HTML da sua documentação

Depois de terminar de compor sua documentação, você pode enviar seu trabalho HTML format executando o comando abaixo:

make html

A saída será salva no diretório ./\_build/htmlque inclui tudo o necessário para visualizar o arquivo em uma navegação na web.

Isso conclui nosso tutorial.