A grande maioria dos projetos da computação da equipe são documentados seguindo a convenção Doxygen, que se auto intitula
The de facto standard tool for generating documentation from annotated C++ sources
Uma das principais funcionalidades do Doxygen é gerar arquivos de documentação no formato HTML, que permite o acesso online dos documentos gerados. Nós poderíamos facilmente utilizar uma action do github pra gerar a documentação automaticamente e acessar pelo GitHub pages, aproveitando a hospedagem do próprio GitHub. No entanto, o próprio GitHub exibe a mensagem de alerta
Caution: This repository is private but the published site will be public.
As páginas do GitHub pages são abertas para todos e não é interessante que qualquer pessoa tenha acesso a esses arquivos. A documentação de um projeto é mais importante do que o próprio código-fonte (melhor do que conseguir o bolo é conseguir a receita do bolo)
Pensando nesse problema, criamos um conjunto de configurações para um servidor nginx com autenticação pelo Google, de modo que qualquer pessoa com email @thunderatz.org é capaz de acessar a página. A autenticação é feita por meio de um app Flask (framework python) que faz a requisição para o site do Google e faz o gerenciamento da sessão do usuário.
Para o carregamento automático da documentação de um projeto, é necessário que:
- O projeto possua um Doxyfile na raiz
- A criação de arquivos html esteja habilitada no Doxyfile
- A documentação seja gerada na pasta docs/Doxygen
- O projeto seja adicionado no arquivo projects.json
- name - Nome do projeto, que será mostrado na página principal
- slug - Nome somente com letras minúsculas, utilizado nas pastas e caminhos
- git - Endereço do repositório do projeto
- branch - Branch cuja documentação será mostrada
- Um cliente faz uma requisição para o algum endereço dentro do docs.thudneratz.org
- O servidor nginx repassa a requisição para a aplicação python
- Caso o cliente ainda não tenha se autenticado, o usuário é levado à página /login para autenticação com a conta do Google
- Caso os dados sejam válidos, o servidor do Google responde com um token de acesso
- Se a autenticação foi bem sucedida, o python puxa os arquivos na pasta requisitada
- O arquivo .html correspondente é carregado
- O arquivo é então enviado ao nginx
- Caso o cliente não tenha se autenticado corretamente, o cliente é redirecionado novamente para a página de login
- O cliente recebe o arquivo requisitado
Para saber mais sobre autenticação OAuth com nginx, veja esse link e essa pergunta no StackOverflow e essa no ruby-forum pra saber como redirecionar requisições de autenticação para o Flask.
Para fazer o deploy da aplicação Flask, é necessário configurar o uWSGI, que será o programa que irá fazer a interface web com o python. Recomendo esse tutorial da DigitalOcean.
O arquivo trdocs.service deve ser copiado para a pasta /etc/systemd/system/
sudo cp ./config/trdocs.service /etc/systemd/system/trdocs.servicePara iniciar o serviço, digite
sudo systemctl start trdocs
sudo systemctl enable trdocsPara fazer a configuração dos certificados de https, utilizamos o certbot. Para o novo domínio, precisamos gerar novos certificados. Recomendo seguir o tutorial oficial, que é bem completo e explicado
Para desenvolvimento local, é necessário que o servidor local tenha suporte a https. Para fazer essa configuração, recomendo esse tutorial. Vou deixar como referência também esse guia com o passo a passo desde o desenvolvimento local até o deploy
- Automatizar atualização da documentação quando so projetos recebem novos commits
- Templates html mais bonitos