From 5469b1fcbef00908f45085da608dbe6a4d0489b6 Mon Sep 17 00:00:00 2001 From: Robson Date: Fri, 2 Feb 2024 11:03:00 -0300 Subject: [PATCH] feat(issue-3): create continuous documentation --- .github/workflows/documentation_deploy.yml | 23 ++++-- Makefile | 12 +++ docs/commands.md | 41 ++++++++++ src/continuous_documentation/__init__.py | 0 .../commands_documentation.py | 75 +++++++++++++++++++ src/main.py | 2 +- 6 files changed, 147 insertions(+), 6 deletions(-) create mode 100644 docs/commands.md create mode 100644 src/continuous_documentation/__init__.py create mode 100644 src/continuous_documentation/commands_documentation.py diff --git a/.github/workflows/documentation_deploy.yml b/.github/workflows/documentation_deploy.yml index 1c9c664..7cdfa29 100644 --- a/.github/workflows/documentation_deploy.yml +++ b/.github/workflows/documentation_deploy.yml @@ -1,8 +1,8 @@ name: documentation_deploy on: push: - branches: - - main +# branches: +# - main jobs: deploy: runs-on: ubuntu-latest @@ -11,6 +11,19 @@ jobs: - uses: actions/setup-python@v2 with: python-version: 3.x - - run: pip install mkdocs - - run: pip install mkdocs-material - - run: mkdocs gh-deploy --force --clean --verbose + + - name: Install Dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + + - name: Create .env + run: | + touch .env + echo DISCORD_SERVER_ID= ${{ secrets.DISCORD_SERVER_ID }} >> .env + + - name: Reload documentations + run: make local_doc + + - name: Run deploy on gh-pages + run: mkdocs gh-deploy --force --clean --verbose diff --git a/Makefile b/Makefile index c5582d7..42befbb 100644 --- a/Makefile +++ b/Makefile @@ -13,3 +13,15 @@ up: test: python3 -m pytest + +local_doc: + @echo 'RUNNING DOCUMENTATION SCRIPTS' + @for script in ./src/continuous_documentation/*.py; do \ + echo 'Running script:' $$script; \ + python3 -m src.continuous_documentation."$$(basename "$$script" .py)"; \ + done + + +build_doc: + mkdocs build + mkdocs serve diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..e820a40 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,41 @@ +# Documentação dos comandos do Bot + +Esta documentação fornece informações detalhadas sobre os comandos disponíveis no Bot Discord. +Em vez de depender de um README estático, esta documentação é construída automáticamente no deploy +usando código Python. +Isso nos permite manter a dinamicidade do mapeamento dos comandos, garantindo que +as informações estejam sempre atualizadas. + +> Para visualizar o código responsável por gerar esta documentação dinâmica, +> clique [aqui](../src/continuous_documentation/commands_documentation.py) + +## Informações sobre os comandos + +Hoje temos **2** comandos. + +Mostramos na tabela abaixo quais são eles e suas informações de forma sintetizada. + +ID |Nome do Comando| Descrição | Aceita Parametros | +---|---------------|-----------|-------------------| +1 | [hello](#hello) | teste de descrição | ❌ +2 | [help](#help) | teste de descrição | ✅ + + +## Comandos de forma detalhada + +### hello + - Descrição: teste de descrição + +**Parâmetros**: + + +___ +### help + - Descrição: teste de descrição + +**Parâmetros**: + +- Nome: command; +- Descrição: comando que o usuário precisa de mais detalhes; +- Obrigatório: ❌. +___ diff --git a/src/continuous_documentation/__init__.py b/src/continuous_documentation/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/src/continuous_documentation/commands_documentation.py b/src/continuous_documentation/commands_documentation.py new file mode 100644 index 0000000..e0197e5 --- /dev/null +++ b/src/continuous_documentation/commands_documentation.py @@ -0,0 +1,75 @@ +from src.main import bot +from src.main import server_id + +string_template = """# Documentação dos comandos do Bot + +Esta documentação fornece informações detalhadas sobre os comandos disponíveis no Bot Discord. +Em vez de depender de um README estático, esta documentação é construída automáticamente no deploy +usando código Python. +Isso nos permite manter a dinamicidade do mapeamento dos comandos, garantindo que +as informações estejam sempre atualizadas. + +> Para visualizar o código responsável por gerar esta documentação dinâmica, +> clique [aqui](../src/continuous_documentation/commands_documentation.py) + +## Informações sobre os comandos + +Hoje temos **{COMMANDS_COUNT}** comandos. + +Mostramos na tabela abaixo quais são eles e suas informações de forma sintetizada. + +ID |Nome do Comando| Descrição | Aceita Parametros | +---|---------------|-----------|-------------------| +{COMMANDS_TABLE} + +## Comandos de forma detalhada + +{COMMANDS_DETAILED} + +""" + + +def docs_dags_self_documentation(): + final_path = './docs/commands.md' + + with open(final_path, 'w') as file: + all_commands = [ + _command for _command in bot.tree.walk_commands(guild=server_id) + ] + commands_count = len(all_commands) + commands_table = '' + commands_detailed = '' + for e, command in enumerate(all_commands, 1): + dict_command = command.to_dict() + accept_commands = '✅' if len(dict_command['options']) > 0 else '❌' + command_name = dict_command['name'] + command_description = dict_command['description'] + + _command_table = f'{e} | [{command_name}](#{command_name}) | {command_description} | {accept_commands}\n' + commands_table += _command_table + + params = '**Parâmetros**:\n\n' + for param in dict_command['options']: + param_name = param['name'] + param_description = param['description'] + param_required = '❌' if param['required'] is False else '✅' + + if len(dict_command['options']) > 0: + params += ( + f'- Nome: {param_name};\n- Descrição: {param_description};\n- Obrigatório: {param_required}.' + ) + + _command_detail = f'### {command_name}\n - Descrição: {command_description}\n\n{params}' + commands_detailed += _command_detail + commands_detailed += '\n___\n' # horizontal line + + commands_documentation = string_template.format( + COMMANDS_COUNT=commands_count, + COMMANDS_TABLE=commands_table, + COMMANDS_DETAILED=commands_detailed, + ) + file.write(commands_documentation) + + +if __name__ == '__main__': + docs_dags_self_documentation() diff --git a/src/main.py b/src/main.py index c8a1f8c..5eafdd8 100644 --- a/src/main.py +++ b/src/main.py @@ -35,7 +35,7 @@ async def hello(interaction: discord.Interaction): @bot.tree.command(name='help', guild=server_id, description='teste de descrição') -@app_commands.describe(command='comando que precisa de mais detalhes') +@app_commands.describe(command='comando que o usuário precisa de mais detalhes') async def help(interaction: discord.Interaction, command: Optional[str] = None): if command is None: embed = discord.Embed(