Criando documentações em reStructuredText com Sphinx – Parte2

Olá, no último post, você viu:

  1. O que é Sphinx
  2. Como instalar o Sphinx
  3. O que é reStructuredText e como é sua sintaxe
  4. Como configurar um tema em sua documentação

Nesta parte do post vou mostrar como ativar o recurso de “live reload” para facilitar o trabalho durante a escrita de sua documentação, como fazer o upload da documentação para um repositório Git e publicar essa documentação utilizando o Read The Docs.

Utilizando atualização em tempo real de navegador sphinx-autobuild

Para instalar o sphinx-autobuild siga os seguintes passos:

1. Execute o seguinte comando para instalar o python live reload:

pip install https://github.com/lepture/python-livereload/archive/master.zip

2. Em seguida, instale o sphinx-autobuild via pip:

pip install sphinx-autobuild

3. Altere seu arquivo Makefile inserindo mais uma task do sphinx:

.PHONY: livehtml
livehtml:
 sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

makefile

E pronto.. Você pode abrir seu navegador e acessar: http://127.0.0.1:8000/ e perceberá que os arquivos .rst estarão em modo –watch, ou seja, assim que salvar um documento seu navegador ira atualizar a página refletindo as alterações automaticamente.

liveReload

Fazendo upload da sua documentação para o git

Neste tutorial eu suponho que você conhece o Github e sabe como criar um repositório, dar um commit e push em seus arquivos. Caso tenha dificuldades de uma olhada neste link.

1. Crie um repositório novo no git:

createRepo

2. Execute seu primeiro commit e push de seus arquivos no repositório utilizando os comandos:

repoUpload

3. Agora você deverá acessar a opção “Settings” dentro do repositório no Git e na sequencia acessar “Webhooks & Services

gitService1

4. Clique no botão “Add Service” e procure por “ReadTheDocs”:

gitService2

5. Pronto. Terminamos a parte do Github, agora vamos para o ReadTheDocs.

Importando e disponibilizando sua documentação com ReadTheDocs

Nesta parte vamos importar os dados de nosso repositório no Github e disponibilizar nossa documentação online.

1. Acesse o ReadTheDocs e efetue login ou crie uma conta:

2. Clique no botão “Import Repository” e selecione o repositório onde está armazenada sua documentação:

repos3. Em seguida, selecione “Next” e aguarde uns instantes. Atualize a página algumas vezes para verificar se os processos passaram sem nenhuma falha.

cloning

4. Volte para página principal “Overview” e você verá que o status de build da sua documentação mudou para “Passed”.

triggered

5. Agora basta acessar o endereço localizado em “Short Urls” e compartilhar esse endereço.

O ReadTheDocs possui features para configuração avançada de temas e apontamentos de domínio. Isso conclui nossa experiência com Sphinx, reStructureText e ReadTheDocs!

Até a próxima!  😉

Anúncios