O desenvolvimento de uma wiki única para a centralização de informações e dados coletados é essencial para a gestão de conhecimento de qualquer projeto ou equipe, já que através de uma página deste tipo, fica fácil para que qualquer um possa consultar o conhecimento técnico e teórico necessário para o desenvolvimento de suas tarefas dentro de um time. Além do mais, pode-se incluir guias e tutoriais dentro de uma wiki, assim, um novo membro terá facilidade para instalar qualquer software necessário e poderá ficar mais por dentro do funcionamento dos processos e tarefas realizados dentro da equipe.
Existem diversas ferramentas disponíveis na web capazes de auxiliar na criação de uma wiki online e moderna, porém, aqui, será abordado a documentação com Sphinx. O Sphinx trata-se de uma ferramenta open-source desenvolvida utilizando o Python e com a finalidade de auxiliar na escrita da extensa documentação desta linguagem, porém, posteriormente sendo adaptada para o desenvolvimento de qualquer tipo de documentação dentro do âmbito de projetos, seja projeto de software ou não.
A linguagem de marcação desta ferramenta é o reStructuredText, uma linguagem poderosa que equipa a documentação Sphinx com sua facilidade de escrita e tradução.
Na tabela abaixo são apresentadas algumas das características e qualidades principais da documentação com o Sphinx:
| Formatos de Saída | HTML, LaTeX, ePub, Texinfo, Páginas Manuais, Texto Plano |
| Cross-References | Marcação semântica e links automáticos, para funções, classes, citações e afins |
| Estrutura Hierárquica | Fácil criação de uma árvore de documentação, com links automáticos para os filhos, parentes e irmãos |
| Índices Automáticos | Índice geral e índices específicos para a linguagem |
| Manipulação do Código | Destaque automático usando o destacador Pygments |
| Extensões | Teste automático de snippets de código, inclusão de docstrings do Python e afins |
| Extensões com Contribuição | Dezenas de extensões com contribuições dos usuários, com a maioria podendo ser instalada através do PyPi |
Apesar da ferramenta Sphinx ser bem completa e útil, certas funcionalidades não estão presentes na mesma, por isso, faz-se necessário o uso de temas para a expansão de funcionalidades ao criar uma documentação. Um destes temas trata-se do Read the docs, um tema open-source que expande as funções da documentação com o Sphinx permitindo versionar e hospedar automaticamente na web uma documentação, além do mais, este tema facilita a conversão de código para documentação escrita, tornando muito mais fácil a criação de novos documentos.
Para instalar a ferramenta é simples, partindo da noção que a última versão do Python já está instalada em sua máquina, abra o Prompt de Comando (ou o equivalente em seu sistema operacional) e digite:
pip install -U sphinx
Após a instalação, digite sphinx-build –version. Se tudo ocorreu corretamente, você verá no próprio Prompt a versão do Sphinx que você acabou de instalar.
Com o Sphinx devidamente instalado e a noção de funcionalidade básica das ferramentas que utilizaremos, vamos aprender a como criar um projeto Sphinx e seu ambiente de desenvolvimento: Primeiramente, é necessário escolher um diretório novo que hospedará todo o seu projeto, e neste diretório, crie um arquivo nomeado como “README.rst”.
Neste arquivo, insira o título de sua documentação e uma breve explicação do que se trata:
No “README.rst”:
Título Escolhido ================ **Título Escolhido** Nesta região, escreva uma breve explicação sobre o que esta documentação se tratará e qual é o público alvo principal desejado
Com o README criado, vamos criar o layout principal da documentação. Para isso, no Prompt de Comando, deve se utilizar o comando cd seguido do endereço do diretório criado para abrir o Prompt neste diretório
cd C:\...\...\...\"diretório do projeto"
Com o Prompt já aberto no diretório de criação do projeto da documentação, basta digitar o comando:
sphinx-quickstart docs
Se tudo foi executado corretamente, uma série de perguntas serão apresentadas para a configuração básica do layout e do projeto dentro da pasta docs. Para cada pergunta é recomendada a seguinte resposta (desconsiderando as aspas):
- Separate source and build directories (y/n) [n]: “y”
- Project name: “Digite o nome escolhido para o projeto”
- Author name(s): “Digite o nome do autor da documentação”
- Project release []: Escreva “0.1”
- Project language [en]: Digite “pt_BR” se deseja escrever um documento em portugues do Brasil, caso deseje em inglês, deixe a resposta vazia e pressione Enter.
Caso tudo tenha ocorrido perfeitamente, a seguinte mensagem será disponibilizada no Prompt:
Finished: An initial directory structure has been created. You should now populate your master file C:\Users\adria\OneDrive\Documents\doc\docs\source\index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
Isto significa que o diretório de estrutura do seu projeto foi criado com sucesso e um nova pasta docs foi criada na pasta principal do projeto.
A organização desta pasta é dada da seguinte forma:
docs ├── build ├── make.bat ├── Makefile └── source ├── conf.py ├── index.rst ├── _static └── _templates
Cada arquivo tem uma especificação única na estruturação do projeto da documentação:
- build/: É a pasta que vai armazenar a documentação renderizada.
- make.bat e Makefile: Script de operações do Sphinx.
- source/index.rst: Este é o documento principal do projeto, que serve como página de introdução e boas-vindas, além de conter a árvore de conteúdos da documentação.
Agora, para compilar o que foi feito até agora, basta digitar o seguinte comando no Prompt:
sphinx-build -b html docs/source/ docs/build/html
Basta abrir o caminho docs/build/html/index.html no navegador que você poderá visualizar sua página de boas-vindas que deverá se parecer com isto:
Com a página básica criada, vamos editá-la e inserir novas páginas conectadas à guia inicial. Para isto, primeiramente devemos abrir a pasta do projeto em uma IDE de preferência, como o Atom ou o VSCode.
Em docs/build/html abrimos o arquivo index.rst que deve ser semelhante ao seguinte:
Para editarmos nossa documentação, editamos a partir deste arquivo aberto no VSCode. Para adicionarmos um novo título basta digitar o título desejado e logo abaixo inserir “=====”, e para escrever algo após o título, simplesmente escrevemos o que desejamos após este título.
Para adicionarmos novas seções ao código, devemos primeiramente criar na mesma pasta do index.rst novos arquivos .rst com nomes distintos para cada arquivo, estes arquivos serão onde colocaremos o conteúdo das novas seções. Com os arquivos .rst adicionados, podemos apagar a linha do “:caption: Contents:” e inserir pulando uma linha abaixo do “maxdepth” o nome dos arquivos de seções criadas, com cada nome estando em uma linha distinta. Um detalhe importante é inserir um título em cada arquivo de seção novo, pois é assim que o Sphinx irá referenciar este novo arquivo na página inicial.
Para darmos um título à aba de seções, antes de “.. toctree::” simplesmente inserimos o nome desejado com “^^^” abaixo.
Para compilarmos as novas alterações, basta digitar no Prompt “make html” e logo após, abrir o index.html no navegador novamente.
Aqui vai um exemplo das modificações no index.rst com seu respectivo resultado:
- index.rst:
Título do seu Documento ======================= Para adicionar um exemplo de código basta adicionarmos ":: "ao final da linha, pular uma linha, e logo abaixo digitar o código desejado, como o seguinte exemplo.:: print 'insira o código' >> resultado... Novo Título ======================= Para criar um novo título basta escrever o que deseja e logo abaixo, inserir os caracteres "=" até que cubra todo o título, assim como o exemplo acima! Guia ^^^^ .. toctree:: :maxdepth: 2 secao 1 secao 2 secao 3 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
- secao 1.rst
Título da Seção 1 ================= Para o Sphinx compilar a seção, é necessário inserir alguma Header para a mesma, portanto, não esqueça de adicionar um título!
- secao 2.rst
Título da Seção 2 ================= Para o Sphinx compilar a seção, é necessário inserir alguma Header para a mesma, portanto, não esqueça de adicionar um título!
- secao 3.rst
Título da Seção 3 ================= Para o Sphinx compilar a seção, é necessário inserir alguma Header para a mesma, portanto, não esqueça de adicionar um título!
Resultados:
A partir deste guia introdutório, fica fácil criar uma wiki única e personalizada para seu projeto, agora restando apenas aprender a utilizar o tema Read the docs para a disponibilização da wiki em uma página da web, facilitando o acesso da mesma. Para isso, é necessário criar uma conta no site Read the docs através do link: ‘https://readthedocs.org/accounts/signup/’, e conectar sua conta recém criada com o GitHub.
Com esta etapa feita, no Prompt, digite:
pip install sphinx_rtd_theme
Agora, no arquivo conf.py, localizado em docs/source, insira o seguinte:
import sphinx_rtd_theme html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
Assim, seu projeto está configurado com o tema Read the docs. Finalmente, basta criar um novo repositório no GitHub com o diretório docs que acabamos de criar, ir na opção de importar um novo projeto no site do Read the docs, selecionar o repositório onde o projeto foi disponibilizado, configurar o nome e as características da forma que desejar e pronto!
Sua wiki está criada e já foi disponibilizada online e deve se parecer um pouco com isto:
Com tudo que foi aprendido, basta botar todas as ideias em prática e criar uma página personalizada centralizando todas as informações importantes de seu projeto para que sua equipe tenha facilidade em acessar todo o conhecimento acumulado. No Cheetah E-Racing utilizamos da documentação Sphinx aliada com o Read the docs para criar nossa própria Wiki, 100% única e funcional!
E aí, gostou de conhecer mais sobre essas ferramentas? Fique ligado nos próximos posts!
Esse post é resultado da parceria da MakerHero com a Cheetah E-Racing. Você pode conferir mais conteúdos feitos pela Cheetah no seguinte link.
E não esqueça de acompanhar a Cheetah E-Racing nas redes sociais. 😀
