moodle-docs-theme 0.1.0__tar.gz → 0.2.0__tar.gz

{moodle_docs_theme-0.1.0 → moodle_docs_theme-0.2.0}/MANIFEST.in

@@ -4,3 +4,4 @@ include moodle_docs_theme/theme.conf
 include moodle_docs_theme/theme.toml
 include moodle_docs_theme/*.html
 recursive-include moodle_docs_theme/static *
+recursive-include moodle_docs_theme/template *

{moodle_docs_theme-0.1.0/moodle_docs_theme.egg-info → moodle_docs_theme-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moodle-docs-theme
-Version: 0.1.0
+Version: 0.2.0
 Summary: Um tema Sphinx reutilizável inspirado visualmente na documentação oficial do Moodle (docs.moodle.org)
 Home-page: https://github.com/moodle-by-kelsoncm/moodle-docs-theme
 Author: KelsonCM
@@ -25,6 +25,10 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: sphinx>=4.0
+Requires-Dist: myst-parser>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -128,6 +132,35 @@ para a lista completa de opções.
 
 ---
 
+## Template de documentação para repositórios
+
+O `moodle-docs-theme` inclui um template completo e padronizado para estruturar a documentação de qualquer repositório ou plugin Moodle da organização:
+
+### Inicialização via CLI
+
+```bash
+# No diretório raiz do plugin
+moodle-docs-theme init
+```
+
+O comando detecta o tipo de plugin, configura o `docs/conf.py` (com suporte a Markdown nativo via `myst-parser`), cria as páginas modelo (`index.md`, `installation.md`, `configuration.md`, `usage.md`), `docs/requirements.txt` e o workflow do GitHub Actions em `.github/workflows/docs.yml`.
+
+### Compilando a documentação
+
+Para compilar a documentação do projeto atual:
+
+```bash
+moodle-docs-theme build
+```
+
+Ou para compilar a documentação do próprio tema:
+
+```bash
+python build_docs.py
+```
+
+---
+
 ## Estrutura do repositório
 
 ```
@@ -140,7 +173,8 @@ moodle-docs-theme/
 │   ├── conf.py
 │   ├── index.rst
 │   ├── installation.rst
-│   └── configuration.rst
+│   ├── configuration.rst
+│   └── template.rst           # Guia de uso do template
 ├── moodle_docs_theme/         # Código fonte do tema Sphinx
 │   ├── static/
 │   │   ├── css/
@@ -148,6 +182,11 @@ moodle-docs-theme/
 │   │   │   └── colors.css
 │   │   └── js/
 │   │       └── theme.js
+│   ├── template/              # Arquivos modelo do template de documentação
+│   │   ├── docs/
+│   │   └── workflows/
+│   ├── cli.py                 # CLI moodle-docs-theme (init, build)
+│   ├── __main__.py
 │   ├── layout.html
 │   ├── page.html
 │   ├── searchbox.html
@@ -155,6 +194,9 @@ moodle-docs-theme/
 │   ├── theme.conf
 │   ├── theme.toml
 │   └── __init__.py
+├── template/                  # Template de documentação exposto na raiz
+├── tests/                     # Testes automatizados (pytest)
+├── build_docs.py              # Script para gerar a própria documentação
 ├── setup.py
 ├── pyproject.toml
 ├── MANIFEST.in
@@ -168,9 +210,10 @@ moodle-docs-theme/
 
 ```bash
 pip install -e .
-sphinx-build -b html docs docs/_build/html
+python build_docs.py --clean
 ```
 
+
 ---
 
 ## Licença

{moodle_docs_theme-0.1.0 → moodle_docs_theme-0.2.0}/README.md

@@ -96,6 +96,35 @@ para a lista completa de opções.
 
 ---
 
+## Template de documentação para repositórios
+
+O `moodle-docs-theme` inclui um template completo e padronizado para estruturar a documentação de qualquer repositório ou plugin Moodle da organização:
+
+### Inicialização via CLI
+
+```bash
+# No diretório raiz do plugin
+moodle-docs-theme init
+```
+
+O comando detecta o tipo de plugin, configura o `docs/conf.py` (com suporte a Markdown nativo via `myst-parser`), cria as páginas modelo (`index.md`, `installation.md`, `configuration.md`, `usage.md`), `docs/requirements.txt` e o workflow do GitHub Actions em `.github/workflows/docs.yml`.
+
+### Compilando a documentação
+
+Para compilar a documentação do projeto atual:
+
+```bash
+moodle-docs-theme build
+```
+
+Ou para compilar a documentação do próprio tema:
+
+```bash
+python build_docs.py
+```
+
+---
+
 ## Estrutura do repositório
 
 ```
@@ -108,7 +137,8 @@ moodle-docs-theme/
 │   ├── conf.py
 │   ├── index.rst
 │   ├── installation.rst
-│   └── configuration.rst
+│   ├── configuration.rst
+│   └── template.rst           # Guia de uso do template
 ├── moodle_docs_theme/         # Código fonte do tema Sphinx
 │   ├── static/
 │   │   ├── css/
@@ -116,6 +146,11 @@ moodle-docs-theme/
 │   │   │   └── colors.css
 │   │   └── js/
 │   │       └── theme.js
+│   ├── template/              # Arquivos modelo do template de documentação
+│   │   ├── docs/
+│   │   └── workflows/
+│   ├── cli.py                 # CLI moodle-docs-theme (init, build)
+│   ├── __main__.py
 │   ├── layout.html
 │   ├── page.html
 │   ├── searchbox.html
@@ -123,6 +158,9 @@ moodle-docs-theme/
 │   ├── theme.conf
 │   ├── theme.toml
 │   └── __init__.py
+├── template/                  # Template de documentação exposto na raiz
+├── tests/                     # Testes automatizados (pytest)
+├── build_docs.py              # Script para gerar a própria documentação
 ├── setup.py
 ├── pyproject.toml
 ├── MANIFEST.in
@@ -136,9 +174,10 @@ moodle-docs-theme/
 
 ```bash
 pip install -e .
-sphinx-build -b html docs docs/_build/html
+python build_docs.py --clean
 ```
 
+
 ---
 
 ## Licença

{moodle_docs_theme-0.1.0 → moodle_docs_theme-0.2.0}/moodle_docs_theme/__init__.py

@@ -5,7 +5,7 @@ moodle_docs_theme - A reusable Sphinx HTML theme inspired by docs.moodle.org (Mo
 import os
 from typing import Dict, Any
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 
 def get_html_theme_path() -> str:

moodle_docs_theme-0.2.0/moodle_docs_theme/__main__.py

@@ -0,0 +1,8 @@
+"""
+Executable module entrypoint for python -m moodle_docs_theme
+"""
+import sys
+from moodle_docs_theme.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

moodle_docs_theme-0.2.0/moodle_docs_theme/cli.py

@@ -0,0 +1,305 @@
+"""
+CLI para inicialização de templates e geração de documentação com moodle-docs-theme.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, Optional, Sequence
+
+from moodle_docs_theme import __version__
+from moodle_docs_theme.template import get_template_dir
+
+
+def _infer_plugin_info(folder_name: str) -> tuple[str, str]:
+    """
+    Infer Moodle plugin path and directory name based on common prefix conventions.
+    """
+    prefixes: dict[str, str] = {
+        "atto_": "lib/editor/atto/plugins",
+        "tiny_": "lib/editor/tiny/plugins",
+        "tool_": "admin/tool",
+        "block_": "blocks",
+        "mod_": "mod",
+        "local_": "local",
+        "format_": "course/format",
+        "profilefield_": "user/profile/field",
+        "editor_": "lib/editor",
+        "theme_": "theme",
+    }
+    for prefix, plugin_path in prefixes.items():
+        if folder_name.startswith(prefix):
+            dir_name = folder_name[len(prefix):]
+            return plugin_path, dir_name
+    return "local", folder_name
+
+
+def _render_template(template_path: Path, context: Dict[str, str]) -> str:
+    """Render a template file with simple dictionary replacements."""
+    content = template_path.read_text(encoding="utf-8")
+    for key, value in context.items():
+        placeholder = f"{{{{ {key} }}}}"
+        content = content.replace(placeholder, str(value))
+    return content
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """
+    Inicializa a estrutura de documentação no repositório de destino usando o template moodle-docs-theme.
+    """
+    target_path = Path(args.target_dir).resolve()
+    folder_name = target_path.name
+
+    project_name = args.project_name or folder_name
+    repo_name = args.repo or f"moodle-by-kelsoncm/{folder_name}"
+    github_url = f"https://github.com/{repo_name.strip('/')}"
+    tagline = args.tagline or f"Documentação oficial de {project_name}"
+    version = args.version or "1.0.0"
+    year = str(datetime.datetime.now().year)
+
+    inferred_path, inferred_dir = _infer_plugin_info(folder_name)
+    plugin_path = args.plugin_path or inferred_path
+    plugin_dir_name = args.plugin_dir_name or inferred_dir
+
+    context: dict[str, str] = {
+        "project_name": project_name,
+        "repo_name": repo_name,
+        "github_url": github_url,
+        "github_repo": repo_name,
+        "tagline": tagline,
+        "version": version,
+        "year": year,
+        "plugin_path": plugin_path,
+        "plugin_dir_name": plugin_dir_name,
+    }
+
+    template_dir = Path(get_template_dir())
+    template_docs_dir = template_dir / "docs"
+    target_docs_dir = target_path / "docs"
+
+    target_docs_dir.mkdir(parents=True, exist_ok=True)
+
+    files_to_render = [
+        ("conf.py.tpl", "conf.py"),
+        ("index.md.tpl", "index.md"),
+        ("installation.md.tpl", "installation.md"),
+        ("configuration.md.tpl", "configuration.md"),
+        ("usage.md.tpl", "usage.md"),
+    ]
+
+    print(f"-> Inicializando template de documentação em: {target_path}")
+
+    created_files: list[str] = []
+    for src_name, dst_name in files_to_render:
+        src_file = template_docs_dir / src_name
+        dst_file = target_docs_dir / dst_name
+
+        if dst_file.exists() and not args.force:
+            print(f"   [IGNORADO] Arquivo já existe: {dst_file.relative_to(target_path)} (use --force para sobrescrever)")
+            continue
+
+        rendered = _render_template(src_file, context)
+        dst_file.write_text(rendered, encoding="utf-8")
+        created_files.append(str(dst_file.relative_to(target_path)))
+        print(f"   [CRIADO]   {dst_file.relative_to(target_path)}")
+
+    # requirements.txt
+    req_src = template_docs_dir / "requirements.txt"
+    req_dst = target_docs_dir / "requirements.txt"
+    if not req_dst.exists() or args.force:
+        shutil.copy2(req_src, req_dst)
+        created_files.append(str(req_dst.relative_to(target_path)))
+        print(f"   [CRIADO]   {req_dst.relative_to(target_path)}")
+    else:
+        print(f"   [IGNORADO] Arquivo já existe: {req_dst.relative_to(target_path)}")
+
+    # Workflow do GitHub Actions
+    if not args.no_workflow:
+        target_workflows_dir = target_path / ".github" / "workflows"
+        target_workflows_dir.mkdir(parents=True, exist_ok=True)
+        wf_src = template_dir / "workflows" / "docs.yml"
+        wf_dst = target_workflows_dir / "docs.yml"
+        if not wf_dst.exists() or args.force:
+            shutil.copy2(wf_src, wf_dst)
+            created_files.append(str(wf_dst.relative_to(target_path)))
+            print(f"   [CRIADO]   {wf_dst.relative_to(target_path)}")
+        else:
+            print(f"   [IGNORADO] Workflow já existe: {wf_dst.relative_to(target_path)}")
+
+    print(f"\nSucesso: Template de documentação configurado ({len(created_files)} arquivos processados)!")
+    print("Para gerar a documentação localmente, execute:")
+    print(f"   moodle-docs-theme build {target_docs_dir.relative_to(target_path)}\n")
+    return 0
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    """
+    Compila a documentação usando Sphinx e moodle-docs-theme.
+    """
+    docs_dir = Path(args.docs_dir).resolve()
+    output_dir = Path(args.output_dir).resolve()
+
+    if not docs_dir.exists():
+        print(f"Erro: Diretório de documentação não encontrado: '{docs_dir}'", file=sys.stderr)
+        return 1
+
+    conf_file = docs_dir / "conf.py"
+    if not conf_file.exists():
+        print(f"Erro: Arquivo 'conf.py' não encontrado em: '{docs_dir}'", file=sys.stderr)
+        return 1
+
+    if args.clean and output_dir.exists():
+        print(f"-> Limpando diretório de saída: '{output_dir}'")
+        shutil.rmtree(output_dir)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    sphinx_cmd = [
+        sys.executable,
+        "-m",
+        "sphinx",
+        "-b",
+        args.builder,
+    ]
+
+    if args.warnings_as_errors:
+        sphinx_cmd.append("-W")
+
+    sphinx_cmd.extend([str(docs_dir), str(output_dir)])
+
+    print(f"-> Gerando documentação: '{docs_dir}' -> '{output_dir}'")
+    try:
+        result = subprocess.run(sphinx_cmd, check=False)
+        if result.returncode == 0:
+            print(f"\nDocumentação gerada com sucesso em: {output_dir}")
+            index_path = output_dir / "index.html"
+            if index_path.exists():
+                print(f"Página inicial: {index_path}")
+        else:
+            print(f"\nFalha na geração da documentação (código de saída: {result.returncode})", file=sys.stderr)
+        return result.returncode
+    except Exception as exc:
+        print(f"Erro ao executar Sphinx: {exc}", file=sys.stderr)
+        return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for moodle-docs-theme CLI."""
+    parser = argparse.ArgumentParser(
+        prog="moodle-docs-theme",
+        description="CLI do moodle-docs-theme para inicializar templates e compilar documentações.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+        help="Exibe a versão do moodle-docs-theme.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Comando a ser executado")
+
+    # Comando: init
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Inicializa a estrutura de documentação em um repositório a partir do template padrão.",
+    )
+    init_parser.add_argument(
+        "target_dir",
+        nargs="?",
+        default=".",
+        help="Diretório raiz do repositório onde a documentação será inicializada (padrão: diretório atual).",
+    )
+    init_parser.add_argument(
+        "--project-name",
+        help="Nome do projeto / plugin (padrão: nome do diretório).",
+    )
+    init_parser.add_argument(
+        "--repo",
+        help="Caminho do repositório no GitHub (ex.: moodle-by-kelsoncm/atto_justify).",
+    )
+    init_parser.add_argument(
+        "--tagline",
+        help="Subtítulo ou descrição curta do projeto.",
+    )
+    init_parser.add_argument(
+        "--version-str",
+        dest="version",
+        help="Versão inicial da documentação (padrão: 1.0.0).",
+    )
+    init_parser.add_argument(
+        "--plugin-path",
+        help="Caminho relativo da categoria do plugin no Moodle (ex.: lib/editor/atto/plugins).",
+    )
+    init_parser.add_argument(
+        "--plugin-dir-name",
+        help="Nome da pasta do plugin dentro da categoria (ex.: justify).",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Sobrescreve arquivos existentes caso já estejam presentes.",
+    )
+    init_parser.add_argument(
+        "--no-workflow",
+        action="store_true",
+        help="Não gera o workflow do GitHub Actions em .github/workflows/docs.yml.",
+    )
+    init_parser.set_defaults(func=cmd_init)
+
+    # Comando: build
+    build_cmd_parser = subparsers.add_parser(
+        "build",
+        help="Compila a documentação com Sphinx e moodle-docs-theme.",
+    )
+    build_cmd_parser.add_argument(
+        "docs_dir",
+        nargs="?",
+        default="docs",
+        help="Diretório onde reside a documentação (contendo conf.py, padrão: 'docs').",
+    )
+    build_cmd_parser.add_argument(
+        "output_dir",
+        nargs="?",
+        default="docs/_build/html",
+        help="Diretório de saída para os arquivos HTML (padrão: 'docs/_build/html').",
+    )
+    build_cmd_parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="Limpa o diretório de saída antes de compilar.",
+    )
+    build_cmd_parser.add_argument(
+        "--builder",
+        default="html",
+        help="Formato de saída do Sphinx (padrão: 'html').",
+    )
+    build_cmd_parser.add_argument(
+        "-W",
+        "--warnings-as-errors",
+        action="store_true",
+        help="Trata warnings do Sphinx como erros.",
+    )
+    build_cmd_parser.set_defaults(func=cmd_build)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Main CLI entry point."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

moodle_docs_theme-0.2.0/moodle_docs_theme/template/__init__.py

@@ -0,0 +1,10 @@
+"""
+Template files for moodle-docs-theme.
+This file marks the package and provides helper to locate template files.
+"""
+import os
+
+
+def get_template_dir() -> str:
+    """Return the absolute path to the template directory."""
+    return os.path.join(os.path.abspath(os.path.dirname(__file__)))

moodle_docs_theme-0.2.0/moodle_docs_theme/template/docs/conf.py.tpl

@@ -0,0 +1,59 @@
+"""
+Sphinx configuration for {{ project_name }}.
+Documentação gerada com o template moodle-docs-theme.
+"""
+import os
+import sys
+import moodle_docs_theme
+
+# -- Informações do Projeto --------------------------------------------------
+project = "{{ project_name }}"
+copyright = "{{ year }}, Contribuições de KelsonCM à comunidade Moodle"
+author = "KelsonCM"
+release = "{{ version }}"
+
+# -- Configuração Geral ------------------------------------------------------
+extensions = [
+    "sphinx.ext.githubpages",
+    "moodle_docs_theme",
+    "myst_parser",
+]
+
+# Suporte a arquivos reStructuredText (.rst) e Markdown (.md)
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# Configurações do MyST-Parser (Markdown)
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "tasklist",
+]
+myst_heading_anchors = 3
+
+templates_path = []
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+language = "pt_BR"
+
+# -- Opções de Saída HTML ----------------------------------------------------
+html_theme = "moodle_docs_theme"
+html_theme_path = [moodle_docs_theme.get_html_theme_path()]
+
+html_theme_options = {
+    "primary_color": "#6c336d",
+    "secondary_color": "#f98012",
+    "project_name": "{{ project_name }}",
+    "tagline": "{{ tagline }}",
+    "github_url": "{{ github_url }}",
+    "github_repo": "{{ github_repo }}",
+    "github_version": "main",
+    "doc_path": "docs/",
+    "show_edit_on_github": True,
+    "enable_dark_mode": True,
+    "navigation_links": "Início|index, Instalação|installation, Configuração|configuration, Uso|usage",
+}
+
+html_static_path = []

moodle_docs_theme-0.2.0/moodle_docs_theme/template/docs/configuration.md.tpl

@@ -0,0 +1,19 @@
+# Configuração — {{ project_name }}
+
+Após a instalação, configure as opções do plugin na administração do Moodle.
+
+---
+
+## Acessando as Configurações
+
+1. Acesse o Moodle com uma conta com privilégios de administrador.
+2. Navegue até **Administração do Site** > **Plugins**.
+3. Localize **{{ project_name }}** na categoria do plugin.
+
+---
+
+## Parâmetros Disponíveis
+
+| Parâmetro | Tipo | Padrão | Descrição |
+|-----------|------|--------|-----------|
+| `enabled` | Booleano | Sim | Ativa ou desativa as funcionalidades do plugin. |

moodle_docs_theme-0.2.0/moodle_docs_theme/template/docs/index.md.tpl

@@ -0,0 +1,19 @@
+# Visão Geral — {{ project_name }}
+
+O **{{ project_name }}** é um componente desenvolvido e mantido pela organização [moodle-by-kelsoncm](https://github.com/moodle-by-kelsoncm) para o ecossistema Moodle.
+
+---
+
+## 🚀 Principais Recursos
+
+- **Recurso 1**: Descrição do primeiro recurso principal do componente.
+- **Recurso 2**: Descrição do segundo recurso principal.
+- **Compatibilidade**: Projetado para Moodle 4.x e versões compatíveis.
+
+---
+
+## 📚 Tópicos da Documentação
+
+- 📦 **[Instalação](installation.md)** — Como instalar o componente manualmente ou via Git.
+- ⚙️ **[Configuração](configuration.md)** — Como configurar e parametrizar o plugin no Moodle.
+- 📖 **[Guia de Uso](usage.md)** — Instruções detalhadas de utilização e fluxos recomendados.

moodle_docs_theme-0.2.0/moodle_docs_theme/template/docs/installation.md.tpl

@@ -0,0 +1,40 @@
+# Instalação — {{ project_name }}
+
+Este guia descreve os passos para instalar o **{{ project_name }}** no seu ambiente Moodle.
+
+---
+
+## Requisitos
+
+- **Moodle**: 4.0 ou superior (recomendado Moodle 4.5+).
+- **PHP**: 8.1 ou superior (recomendado PHP 8.3+).
+- Permissões de escrita no diretório do plugin durante a instalação.
+
+---
+
+## Métodos de Instalação
+
+### 1. Via Git (Recomendado para Desenvolvimento)
+
+Clone o repositório diretamente no diretório apropriado do seu Moodle:
+
+```bash
+cd /caminho/do/moodle/{{ plugin_path }}
+git clone {{ github_url }}.git {{ plugin_dir_name }}
+```
+
+### 2. Via Pacote ZIP
+
+1. Baixe o arquivo `.zip` da release mais recente no [GitHub Releases]({{ github_url }}/releases).
+2. Extraia o conteúdo na pasta correspondente do Moodle (`{{ plugin_path }}/{{ plugin_dir_name }}`).
+3. Acesse a administração do Moodle (*Administração do Site > Notificações*) para concluir a instalação do banco de dados.
+
+---
+
+## Pós-Instalação
+
+Após a instalação, purgue os caches do Moodle:
+
+```bash
+php admin/cli/purge_caches.php
+```

moodle_docs_theme-0.2.0/moodle_docs_theme/template/docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx>=7.0
+myst-parser>=2.0
+moodle-docs-theme>=0.1.0

moodle_docs_theme-0.2.0/moodle_docs_theme/template/docs/usage.md.tpl

@@ -0,0 +1,21 @@
+# Guia de Uso — {{ project_name }}
+
+Instruções práticas e fluxos de trabalho para o **{{ project_name }}**.
+
+---
+
+## Fluxo de Trabalho
+
+Descreva aqui as etapas principais para utilizar o plugin no dia a dia do Moodle.
+
+---
+
+## Exemplos Práticos
+
+### Caso 1: Utilização Básica
+
+Explique o cenário comum de utilização pelo usuário final ou professor.
+
+### Caso 2: Utilização Avançada
+
+Explique cenários avançados de integração ou automação.

moodle_docs_theme-0.2.0/moodle_docs_theme/template/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx myst-parser moodle-docs-theme
+
+      - name: Build Documentation with Sphinx
+        run: |
+          sphinx-build -W -b html docs docs/_build/html
+
+      - name: Upload Pages Artifact
+        if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy-docs:
+    name: Deploy to GitHub Pages
+    if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') && github.event_name != 'pull_request'
+    needs: build-docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{moodle_docs_theme-0.1.0 → moodle_docs_theme-0.2.0/moodle_docs_theme.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moodle-docs-theme
-Version: 0.1.0
+Version: 0.2.0
 Summary: Um tema Sphinx reutilizável inspirado visualmente na documentação oficial do Moodle (docs.moodle.org)
 Home-page: https://github.com/moodle-by-kelsoncm/moodle-docs-theme
 Author: KelsonCM
@@ -25,6 +25,10 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: sphinx>=4.0
+Requires-Dist: myst-parser>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -128,6 +132,35 @@ para a lista completa de opções.
 
 ---
 
+## Template de documentação para repositórios
+
+O `moodle-docs-theme` inclui um template completo e padronizado para estruturar a documentação de qualquer repositório ou plugin Moodle da organização:
+
+### Inicialização via CLI
+
+```bash
+# No diretório raiz do plugin
+moodle-docs-theme init
+```
+
+O comando detecta o tipo de plugin, configura o `docs/conf.py` (com suporte a Markdown nativo via `myst-parser`), cria as páginas modelo (`index.md`, `installation.md`, `configuration.md`, `usage.md`), `docs/requirements.txt` e o workflow do GitHub Actions em `.github/workflows/docs.yml`.
+
+### Compilando a documentação
+
+Para compilar a documentação do projeto atual:
+
+```bash
+moodle-docs-theme build
+```
+
+Ou para compilar a documentação do próprio tema:
+
+```bash
+python build_docs.py
+```
+
+---
+
 ## Estrutura do repositório
 
 ```
@@ -140,7 +173,8 @@ moodle-docs-theme/
 │   ├── conf.py
 │   ├── index.rst
 │   ├── installation.rst
-│   └── configuration.rst
+│   ├── configuration.rst
+│   └── template.rst           # Guia de uso do template
 ├── moodle_docs_theme/         # Código fonte do tema Sphinx
 │   ├── static/
 │   │   ├── css/
@@ -148,6 +182,11 @@ moodle-docs-theme/
 │   │   │   └── colors.css
 │   │   └── js/
 │   │       └── theme.js
+│   ├── template/              # Arquivos modelo do template de documentação
+│   │   ├── docs/
+│   │   └── workflows/
+│   ├── cli.py                 # CLI moodle-docs-theme (init, build)
+│   ├── __main__.py
 │   ├── layout.html
 │   ├── page.html
 │   ├── searchbox.html
@@ -155,6 +194,9 @@ moodle-docs-theme/
 │   ├── theme.conf
 │   ├── theme.toml
 │   └── __init__.py
+├── template/                  # Template de documentação exposto na raiz
+├── tests/                     # Testes automatizados (pytest)
+├── build_docs.py              # Script para gerar a própria documentação
 ├── setup.py
 ├── pyproject.toml
 ├── MANIFEST.in
@@ -168,9 +210,10 @@ moodle-docs-theme/
 
 ```bash
 pip install -e .
-sphinx-build -b html docs docs/_build/html
+python build_docs.py --clean
 ```
 
+
 ---
 
 ## Licença

{moodle_docs_theme-0.1.0 → moodle_docs_theme-0.2.0}/moodle_docs_theme.egg-info/SOURCES.txt

@@ -4,7 +4,9 @@ README.md
 pyproject.toml
 setup.py
 moodle_docs_theme/__init__.py
+moodle_docs_theme/__main__.py
 moodle_docs_theme/breadcrumbs.html
+moodle_docs_theme/cli.py
 moodle_docs_theme/layout.html
 moodle_docs_theme/page.html
 moodle_docs_theme/searchbox.html
@@ -18,4 +20,14 @@ moodle_docs_theme.egg-info/requires.txt
 moodle_docs_theme.egg-info/top_level.txt
 moodle_docs_theme/static/css/base.css
 moodle_docs_theme/static/css/colors.css
-moodle_docs_theme/static/js/theme.js
+moodle_docs_theme/static/js/theme.js
+moodle_docs_theme/template/__init__.py
+moodle_docs_theme/template/docs/conf.py.tpl
+moodle_docs_theme/template/docs/configuration.md.tpl
+moodle_docs_theme/template/docs/index.md.tpl
+moodle_docs_theme/template/docs/installation.md.tpl
+moodle_docs_theme/template/docs/requirements.txt
+moodle_docs_theme/template/docs/usage.md.tpl
+moodle_docs_theme/template/workflows/docs.yml
+tests/test_cli.py
+tests/test_theme.py

moodle_docs_theme-0.2.0/moodle_docs_theme.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+moodle-docs-theme = moodle_docs_theme.cli:main
+
+[sphinx.html_themes]
+moodle_docs_theme = moodle_docs_theme

moodle_docs_theme-0.2.0/moodle_docs_theme.egg-info/requires.txt

@@ -0,0 +1,6 @@
+sphinx>=4.0
+myst-parser>=2.0
+
+[dev]
+pytest>=7.0
+pytest-cov

{moodle_docs_theme-0.1.0 → moodle_docs_theme-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "moodle-docs-theme"
-version = "0.1.0"
+version = "0.2.0"
 description = "Um tema Sphinx reutilizável inspirado visualmente na documentação oficial do Moodle (docs.moodle.org)"
 readme = "README.md"
 authors = [
@@ -13,7 +13,8 @@ authors = [
 license = "BSD-3-Clause"
 requires-python = ">=3.8"
 dependencies = [
-    "sphinx>=4.0"
+    "sphinx>=4.0",
+    "myst-parser>=2.0"
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -31,10 +32,19 @@ classifiers = [
     "Topic :: Software Development :: Documentation"
 ]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov"
+]
+
 [project.urls]
 Homepage = "https://github.com/moodle-by-kelsoncm/moodle-docs-theme"
 Repository = "https://github.com/moodle-by-kelsoncm/moodle-docs-theme"
 
+[project.scripts]
+moodle-docs-theme = "moodle_docs_theme.cli:main"
+
 [project.entry-points."sphinx.html_themes"]
 moodle_docs_theme = "moodle_docs_theme"
 
@@ -49,4 +59,6 @@ moodle_docs_theme = [
     "theme.toml",
     "static/css/*.css",
     "static/js/*.js",
+    "template/docs/*",
+    "template/workflows/*",
 ]

{moodle_docs_theme-0.1.0 → moodle_docs_theme-0.2.0}/setup.py

@@ -6,22 +6,36 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="moodle-docs-theme",
-    version="0.1.0",
+    version="0.2.0",
     author="KelsonCM",
     author_email="kelsoncm@gmail.com",
     description="Um tema Sphinx reutilizável inspirado visualmente na documentação oficial do Moodle (docs.moodle.org)",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/moodle-by-kelsoncm/moodle-docs-theme",
+    install_requires=[
+        "sphinx>=4.0",
+        "myst-parser>=2.0",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=7.0",
+            "pytest-cov",
+        ],
+    },
     packages=find_namespace_packages(include=["moodle_docs_theme*"]),
     include_package_data=True,
     package_data={
         "moodle_docs_theme": [
             "*.html", "theme.conf", "theme.toml",
             "static/css/*.css", "static/js/*.js",
+            "template/docs/*", "template/workflows/*",
         ],
     },
     entry_points={
+        "console_scripts": [
+            "moodle-docs-theme = moodle_docs_theme.cli:main",
+        ],
         "sphinx.html_themes": [
             "moodle_docs_theme = moodle_docs_theme",
         ],

moodle_docs_theme-0.2.0/tests/test_cli.py

@@ -0,0 +1,127 @@
+"""
+Testes unitários para o CLI do moodle-docs-theme.
+"""
+import os
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from moodle_docs_theme.cli import (
+    _infer_plugin_info,
+    _render_template,
+    build_parser,
+    main,
+)
+
+
+class TestMoodleDocsThemeCLI(unittest.TestCase):
+
+    def setUp(self):
+        self.test_dir = tempfile.mkdtemp()
+
+    def tearDown(self):
+        shutil.rmtree(self.test_dir, ignore_errors=True)
+
+    def test_infer_plugin_info(self):
+        self.assertEqual(_infer_plugin_info("atto_justify"), ("lib/editor/atto/plugins", "justify"))
+        self.assertEqual(_infer_plugin_info("tiny_fontfamily"), ("lib/editor/tiny/plugins", "fontfamily"))
+        self.assertEqual(_infer_plugin_info("tool_ribbons"), ("admin/tool", "ribbons"))
+        self.assertEqual(_infer_plugin_info("block_recommendation"), ("blocks", "recommendation"))
+        self.assertEqual(_infer_plugin_info("mod_imagemap"), ("mod", "imagemap"))
+        self.assertEqual(_infer_plugin_info("local_tinytoolbar"), ("local", "tinytoolbar"))
+        self.assertEqual(_infer_plugin_info("format_timeline"), ("course/format", "timeline"))
+        self.assertEqual(_infer_plugin_info("profilefield_json"), ("user/profile/field", "json"))
+        self.assertEqual(_infer_plugin_info("theme_boost"), ("theme", "boost"))
+        self.assertEqual(_infer_plugin_info("custom_repo"), ("local", "custom_repo"))
+
+    def test_render_template(self):
+        tpl_path = Path(self.test_dir) / "template.txt"
+        tpl_path.write_text("Hello {{ name }}! Repo: {{ repo }}", encoding="utf-8")
+        result = _render_template(tpl_path, {"name": "World", "repo": "moodle/org"})
+        self.assertEqual(result, "Hello World! Repo: moodle/org")
+
+    def test_cli_init_default(self):
+        target_dir = Path(self.test_dir) / "tool_sample"
+        target_dir.mkdir()
+
+        exit_code = main(["init", str(target_dir)])
+        self.assertEqual(exit_code, 0)
+
+        docs_dir = target_dir / "docs"
+        self.assertTrue((docs_dir / "conf.py").exists())
+        self.assertTrue((docs_dir / "index.md").exists())
+        self.assertTrue((docs_dir / "installation.md").exists())
+        self.assertTrue((docs_dir / "configuration.md").exists())
+        self.assertTrue((docs_dir / "usage.md").exists())
+        self.assertTrue((docs_dir / "requirements.txt").exists())
+        self.assertTrue((target_dir / ".github" / "workflows" / "docs.yml").exists())
+
+        # Verifica conteúdo renderizado
+        conf_content = (docs_dir / "conf.py").read_text(encoding="utf-8")
+        self.assertIn('project = "tool_sample"', conf_content)
+        self.assertIn('"github_repo": "moodle-by-kelsoncm/tool_sample"', conf_content)
+        self.assertIn('"moodle_docs_theme"', conf_content)
+
+    def test_cli_init_custom_options(self):
+        target_dir = Path(self.test_dir) / "atto_custom"
+        target_dir.mkdir()
+
+        exit_code = main([
+            "init",
+            str(target_dir),
+            "--project-name", "moodle-atto_custom",
+            "--repo", "moodle-by-kelsoncm/atto_custom",
+            "--tagline", "Custom Atto plugin description",
+            "--version-str", "2.1.0",
+            "--no-workflow",
+        ])
+        self.assertEqual(exit_code, 0)
+
+        docs_dir = target_dir / "docs"
+        conf_content = (docs_dir / "conf.py").read_text(encoding="utf-8")
+        self.assertIn('project = "moodle-atto_custom"', conf_content)
+        self.assertIn('release = "2.1.0"', conf_content)
+        self.assertIn('Custom Atto plugin description', conf_content)
+
+        # Sem workflow
+        self.assertFalse((target_dir / ".github" / "workflows" / "docs.yml").exists())
+
+    def test_cli_init_skip_existing_without_force(self):
+        target_dir = Path(self.test_dir) / "existing_repo"
+        target_dir.mkdir()
+        docs_dir = target_dir / "docs"
+        docs_dir.mkdir()
+        (docs_dir / "conf.py").write_text("existing content", encoding="utf-8")
+
+        exit_code = main(["init", str(target_dir)])
+        self.assertEqual(exit_code, 0)
+
+        self.assertEqual((docs_dir / "conf.py").read_text(encoding="utf-8"), "existing content")
+
+        # Com --force deve sobrescrever
+        exit_code = main(["init", str(target_dir), "--force"])
+        self.assertEqual(exit_code, 0)
+        self.assertIn("moodle_docs_theme", (docs_dir / "conf.py").read_text(encoding="utf-8"))
+
+    def test_cli_build_nonexistent_directory(self):
+        nonexistent = str(Path(self.test_dir) / "nao_existe")
+        exit_code = main(["build", nonexistent])
+        self.assertEqual(exit_code, 1)
+
+    def test_cli_build_missing_conf_py(self):
+        empty_dir = str(Path(self.test_dir) / "empty")
+        os.makedirs(empty_dir)
+        exit_code = main(["build", empty_dir])
+        self.assertEqual(exit_code, 1)
+
+    def test_parser_version(self):
+        parser = build_parser()
+        with self.assertRaises(SystemExit) as ctx:
+            parser.parse_args(["--version"])
+        self.assertEqual(ctx.exception.code, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

moodle_docs_theme-0.2.0/tests/test_theme.py

@@ -0,0 +1,72 @@
+"""
+Testes unitários para o tema moodle_docs_theme.
+"""
+import os
+import unittest
+from unittest.mock import MagicMock
+
+import moodle_docs_theme
+
+
+class TestMoodleDocsTheme(unittest.TestCase):
+
+    def test_version(self):
+        self.assertIsNotNone(moodle_docs_theme.__version__)
+        self.assertTrue(len(moodle_docs_theme.__version__) > 0)
+
+    def test_get_html_theme_path(self):
+        theme_path = moodle_docs_theme.get_html_theme_path()
+        self.assertTrue(os.path.isdir(theme_path))
+        self.assertTrue(os.path.exists(os.path.join(theme_path, "theme.conf")))
+        self.assertTrue(os.path.exists(os.path.join(theme_path, "layout.html")))
+
+    def test_setup(self):
+        mock_app = MagicMock()
+        result = moodle_docs_theme.setup(mock_app)
+
+        mock_app.add_html_theme.assert_called_once_with(
+            "moodle_docs_theme", moodle_docs_theme.get_html_theme_path()
+        )
+        self.assertEqual(mock_app.add_css_file.call_count, 2)
+        self.assertEqual(mock_app.add_js_file.call_count, 1)
+        self.assertTrue(result["parallel_read_safe"])
+        self.assertTrue(result["parallel_write_safe"])
+
+    def test_validate_github_actions_config_skipped_locally(self):
+        # Se GITHUB_ACTIONS não for 'true', não deve validar/lançar erro
+        old_val = os.environ.pop("GITHUB_ACTIONS", None)
+        old_run_id = os.environ.pop("GITHUB_RUN_ID", None)
+        try:
+            mock_app = MagicMock()
+            mock_app.config.extensions = []
+            # Não deve lançar exceção
+            moodle_docs_theme.validate_github_actions_config(mock_app)
+        finally:
+            if old_val is not None:
+                os.environ["GITHUB_ACTIONS"] = old_val
+            if old_run_id is not None:
+                os.environ["GITHUB_RUN_ID"] = old_run_id
+
+    def test_validate_github_actions_config_raises_when_missing(self):
+        from sphinx.errors import ExtensionError
+
+        old_val = os.environ.get("GITHUB_ACTIONS")
+        try:
+            os.environ["GITHUB_ACTIONS"] = "true"
+            mock_app = MagicMock()
+            mock_app.config.extensions = ["sphinx.ext.autodoc"]
+
+            with self.assertRaises(ExtensionError) as ctx:
+                moodle_docs_theme.validate_github_actions_config(mock_app)
+
+            self.assertIn("moodle_docs_theme", str(ctx.exception))
+            self.assertIn("sphinx.ext.githubpages", str(ctx.exception))
+        finally:
+            if old_val is not None:
+                os.environ["GITHUB_ACTIONS"] = old_val
+            else:
+                os.environ.pop("GITHUB_ACTIONS", None)
+
+
+if __name__ == "__main__":
+    unittest.main()

moodle_docs_theme-0.1.0/moodle_docs_theme.egg-info/entry_points.txt

@@ -1,2 +0,0 @@
-[sphinx.html_themes]
-moodle_docs_theme = moodle_docs_theme

moodle_docs_theme-0.1.0/moodle_docs_theme.egg-info/requires.txt

@@ -1 +0,0 @@
-sphinx>=4.0