BOSS - Big Open Source Sister

Sistema de documentação e GitHub Pages da organização BOSS - Big Open Source Sister

Dependências

Configuração

Instalando o VirtualEnvWrapper

Recomendados a utilização de um ambiente virtual criado pelo módulo virtualenvwrapper. Existe um sítio virtual com instruções em inglês para a instalação que pode ser acessado aqui. Mas você pode também seguir o roteiro abaixo para a instalação do ambiente:

sudo python3 -m pip install -U pip             # Faz a atualização do pip
sudo python3 -m pip install virtualenvwrapper  # Instala o módulo virtualenvwrapper

OBS: Caso não tenha acesso de administrador na máquina remova o sudo do início do comando e adicione a flag --user ao final do comando.

Agora configure o seu shell para utilizar o virtualenvwrapper, adicionando essas duas linhas ao arquivo de inicialização do seu shell (.bashrc, .profile, etc.)

export WORKON_HOME=\$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh

Caso queira adicionar um local específico de projeto basta adicionar uma terceira linha com o seguinte export:

export PROJECT_HOME=/path/to/project

Execute o arquivo de inicialização do shell para que as mudanças surtam efeito, por exemplo:

source ~/.bashrc

Agora crie um ambiente virtual com o seguinte comando (colocando o nome que deseja para o ambiente), neste exemplo usarei o nome boss:

mkvirtualenv -p $(which python3) boss

Para utilizá-lo:

workon boss
sudo python3 -m pip install pipenv
pipenv install # Irá instalar todas as dependências usadas no projeto

OBS: Novamente, caso necessário, adicione a flag --user para fazer a instalação do pacote do pipenv.

Iniciando o servidor MkDocs

Agora basta executar o comando abaixo para rodar o servidor do MkDocs localmente:

cd boss/
mkdocs serve

Acesse em um navegador o endereço http://127.0.0.1:8000 e seu servidor local do MkDocs deve estar funcionando com live reloading para que você verifique as modificações durante o desenvolvimento.

Análise Estática

Para garantir a qualidade estática, mesmo nas documentações, este projeto faz uso do markdown linter. Este serviço garante que boas práticas na escrita de documentos em Markdown sejam cumpridas.

Para executar o linter basta executar:

gem install mdl
mdl boss

O relatório da execução será aprensentado no terminal. As regras usadas pelo mdl podem ser vistas nesse link: REGRAS

Gerando o CHANGELOG

Este repositório está munido de ferramenta para geração automática de changelog. Faz o uso de um pacote simples em Node.JS o standard-version. Para gerar uma nova revisão e o changelog do repositório execute:

yarn run release # Ou npm caso seja este seu gerenciador de pacotes JS

Para mais informações de uso e documentação apropriada acesse o seguinte link: standard-version