Construindo uma Documentação do Zero - Parte 01 · rikemorais

Resumo

Eu sou um entusiasta do mundo das documentações. Decidi criar esse conteúdo para mostrar para alguns colegas, algumas possibilidades Open Source. Além de gratuito, falaremos de algo realmente bonito de se ver. Abaixo você pode ter uma visão básica do projeto:

Docs

Montando o Ambiente

Clone o Repositório

Primeiro clone este repositório usando o https://github.com/rikemorais/rikemorais.docs.git dentro de um diretório em seu computador.

Crie o Ambiente Virtual

Criar um Ambiente Virtual é uma boa prática de desenvolvimento. Pense da seguinte forma: você instala uma versão de uma biblioteca para um projeto, mas, em outro você precisa de uma versão diferente pois é incompatível por este outro projeto. Ao invés de instalar globalmente, você pode instalar uma versão para cada projeto. Essa é uma das várias importâncias de montar um Ambiente Virtual antes de sair instalando dependências. Siga os seguintes passos:

Abra o Terminal e navegue através dele até a pasta onde está o projeto que você acabou de clonar;

Escreva o seguinte comando: python -m venv venv e pressione a tecla Enter;

Para acessar o seu ambiente virtual você pode usar o comando: venv/Scripts/Activate

Verifique o pip está atualizado com python -m pip install --upgrade pip só para garantir que você está usando a versão mais recente do gerenciador de instalação.

Com isso você poderá seguir para a próxima etapa.

Instale as Dependências

Para garantir que o projeto funcione perfeitamente, recomendo que use as dependências do arquivo requiriments.txt. Você pode instalar usando esse comando: pip install -r requirements.txt. Esse arquivo contém todas as dependências necessárias para o projeto rodar. Mas, se preferir, pode instalar os comandos abaixo.

pip install mkdocs
pip install pymdown-extensions
pip install mkdocs-material
pip install mkdocs-glightbox

Preparando o Ambiente do MkDocs

Será necessário que você gere a Build do seu projeto. Para isso você irá usar dois comandos da biblioteca MkDocs:

mkdocs build - esse comando irá fazer o build da sua aplicação com todas as configurações da pasta site e do arquivo mkdocs.yml.
mkdocs serve - esse é comando que irá rodar a documentação para você usar. Após rodar esse comando, basta dar um Ctrl + clicar no endereço que vai aparecer no seu terminal e acessar o projeto rodando: http://127.0.0.1:8000.

Conclusão

Agora você pode usar a ferramenta para construir sua documentação. Você perceberá que o MkDocs Material funciona com níveis e sub níveis de pastas. E a parte hierárquica funciona com o próprio Markdown. Futuramente, irei postar mais detalhes das configurações.