moodle-docs-theme 0.1.0__py3-none-any.whl

moodle_docs_theme/__init__.py

@@ -0,0 +1,92 @@
+"""
+moodle_docs_theme - A reusable Sphinx HTML theme inspired by docs.moodle.org (MoodleDocs).
+"""
+
+import os
+from typing import Dict, Any
+
+__version__ = "0.1.0"
+
+
+def get_html_theme_path() -> str:
+    """
+    Return the absolute path to the directory containing theme.conf.
+
+    This function is maintained for backward compatibility with older Sphinx theme patterns.
+    Modern Sphinx 1.6+ discovers the theme automatically via entry points.
+    """
+    return os.path.abspath(os.path.dirname(__file__))
+
+
+def validate_github_actions_config(app: Any) -> None:
+    """
+    Validate Sphinx configuration when running inside GitHub Actions.
+
+    If GITHUB_ACTIONS == 'true', ensures that:
+    1. 'moodle_docs_theme' is present in app.config.extensions
+    2. 'sphinx.ext.githubpages' is present in app.config.extensions
+
+    Raises ExtensionError if requirements are not met.
+    """
+    is_github_actions = (
+        os.environ.get("GITHUB_ACTIONS") == "true" or "GITHUB_RUN_ID" in os.environ
+    )
+
+    if not is_github_actions:
+        return
+
+    extensions = getattr(app.config, "extensions", []) or []
+    missing_requirements = []
+
+    if "moodle_docs_theme" not in extensions:
+        missing_requirements.append(
+            "• 'moodle_docs_theme' deve estar listado em 'extensions = [...]' no seu docs/conf.py."
+        )
+
+    if "sphinx.ext.githubpages" not in extensions:
+        missing_requirements.append(
+            "• 'sphinx.ext.githubpages' deve estar listado em 'extensions = [...]' no seu docs/conf.py para gerar o arquivo .nojekyll e evitar que o GitHub Pages bloqueie a pasta _static/."
+        )
+
+    if missing_requirements:
+        error_msg = (
+            "\n"
+            "================================================================================\n"
+            "[moodle_docs_theme] ERRO DE CONFIGURAÇÃO NO GITHUB ACTIONS\n"
+            "================================================================================\n"
+            "Foi detectada a execução dentro do ambiente GitHub Actions, mas as configurações\n"
+            "obrigatórias do tema não foram encontradas no seu 'docs/conf.py':\n\n"
+            + "\n".join(missing_requirements)
+            + "\n\n"
+            "Por favor, certifique-se de atualizar o 'docs/conf.py' do seu projeto:\n\n"
+            "    extensions = [\n"
+            "        'sphinx.ext.autodoc',\n"
+            "        'sphinx.ext.githubpages',\n"
+            "        'moodle_docs_theme',\n"
+            "    ]\n\n"
+            "================================================================================\n"
+        )
+        from sphinx.errors import ExtensionError
+        raise ExtensionError(error_msg)
+
+
+def setup(app: Any) -> Dict[str, Any]:
+    """
+    Sphinx extension setup function.
+
+    Registers the theme with Sphinx when activated in conf.py.
+    """
+    theme_path = get_html_theme_path()
+    app.add_html_theme("moodle_docs_theme", theme_path)
+
+    app.add_css_file("css/colors.css")
+    app.add_css_file("css/base.css")
+    app.add_js_file("js/theme.js")
+
+    app.connect("builder-inited", validate_github_actions_config)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

moodle_docs_theme/breadcrumbs.html

@@ -0,0 +1,38 @@
+{# Breadcrumbs navigation bar #}
+<div class="moodle-breadcrumbs-bar">
+  <div class="moodle-breadcrumbs-inner">
+    <nav aria-label="Breadcrumbs">
+      <ul class="moodle-breadcrumbs">
+        <li>
+          <a href="{{ pathto(master_doc) }}">{{ _('Início') }}</a>
+        </li>
+        {% for parent in parents %}
+          <li>
+            <a href="{{ parent.link|e }}">{{ parent.title }}</a>
+          </li>
+        {% endfor %}
+        {% if pagename != master_doc %}
+          <li aria-current="page">
+            <span>{{ title|striptags }}</span>
+          </li>
+        {% endif %}
+      </ul>
+    </nav>
+
+    {# Edit on GitHub link #}
+    {% if theme_show_edit_on_github|tobool and (theme_github_url or theme_github_repo) %}
+      {% set gh_repo = theme_github_repo if theme_github_repo else (theme_github_url.rstrip('/').split('/')[-2:] | join('/')) %}
+      {% set gh_version = theme_github_version if theme_github_version else 'main' %}
+      {% set gh_doc_path = theme_doc_path if theme_doc_path else 'docs/' %}
+      {% set file_ext = page_source_suffix if page_source_suffix and page_source_suffix is string else '.rst' %}
+      {% set edit_url = "https://github.com/" ~ gh_repo ~ "/edit/" ~ gh_version ~ "/" ~ gh_doc_path.rstrip('/') ~ "/" ~ pagename ~ file_ext %}
+      <a href="{{ edit_url }}" class="edit-on-github-link" target="_blank" rel="noopener noreferrer" title="Editar esta página no GitHub">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"></path>
+          <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"></path>
+        </svg>
+        <span>Editar no GitHub</span>
+      </a>
+    {% endif %}
+  </div>
+</div>

moodle_docs_theme/layout.html

@@ -0,0 +1,179 @@
+{% extends "basic/layout.html" %}
+
+{% block doctype %}
+<!DOCTYPE html>
+{% endblock %}
+
+{% block htmltag %}
+<html lang="{{ language if language else 'pt-BR' }}">
+{% endblock %}
+
+{% block extrahead %}
+  {{ super() }}
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+  {# Script inline de inicialização instantânea do Dark Mode (Evita FOUC) #}
+  <script>
+    (function() {
+      try {
+        var storedTheme = localStorage.getItem('moodle-theme');
+        var systemPrefersDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
+        var theme = storedTheme || (systemPrefersDark ? 'dark' : 'light');
+        if (theme === 'dark') {
+          document.documentElement.setAttribute('data-theme', 'dark');
+        } else {
+          document.documentElement.removeAttribute('data-theme');
+        }
+      } catch (e) {}
+    })();
+  </script>
+
+  {# Carregamento da fonte Open Sans via Google Fonts (mesma família usada no docs.moodle.org) #}
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300;0,400;0,600;0,700;1,400&display=swap" rel="stylesheet">
+
+  {# Dynamic CSS Variable overrides from theme_options #}
+  <style>
+    :root {
+      {% if theme_primary_color %}--moodle-primary: {{ theme_primary_color }};{% endif %}
+      {% if theme_secondary_color %}--moodle-accent: {{ theme_secondary_color }}; --moodle-header-border: {{ theme_secondary_color }};{% endif %}
+      {% if theme_accent_color %}--moodle-sub-header-bg: {{ theme_accent_color }};{% endif %}
+      {% if theme_text_color %}--moodle-text: {{ theme_text_color }};{% endif %}
+      {% if theme_bg_color %}--moodle-bg: {{ theme_bg_color }};{% endif %}
+      {% if theme_code_bg_color %}--moodle-code-bg: {{ theme_code_bg_color }};{% endif %}
+      {% if theme_link_color %}--moodle-link: {{ theme_link_color }};{% endif %}
+      {% if theme_link_hover_color %}--moodle-link-hover: {{ theme_link_hover_color }};{% endif %}
+      {% if theme_sidebar_bg %}--moodle-sidebar-bg: {{ theme_sidebar_bg }};{% endif %}
+      {% if theme_nav_text_color %}--moodle-nav-text: {{ theme_nav_text_color }};{% endif %}
+    }
+  </style>
+{% endblock %}
+
+{% block header %}
+<div class="moodle-site-wrapper">
+  {# 1. Top Header Bar (Estilo MoodleDocs: fundo claro, marca à esquerda, faixa laranja inferior) #}
+  <header class="moodle-header">
+    <div class="moodle-header-inner">
+      {# Brand Logo & Name #}
+      <div class="moodle-brand-group">
+        <a href="{{ pathto(master_doc) }}" class="moodle-brand">
+          {% if theme_logo %}
+            <img src="{{ pathto('_static/' ~ theme_logo, 1) }}" alt="{{ project }}" class="moodle-brand-logo" style="{% if theme_logo_height %}height: {{ theme_logo_height }};{% endif %}" />
+          {% elif logo_url %}
+            <img src="{{ logo_url }}" alt="{{ project }}" class="moodle-brand-logo" />
+          {% elif logo %}
+            <img src="{{ pathto('_static/' ~ logo, 1) }}" alt="{{ project }}" class="moodle-brand-logo" />
+          {% else %}
+            <span class="moodle-brand-title">
+              {% if theme_project_name %}{{ theme_project_name }}{% else %}{{ project }}{% endif %}
+            </span>
+          {% endif %}
+        </a>
+        <span class="moodle-tagline">
+          {% if theme_tagline %}{{ theme_tagline }}{% else %}Documentação inspirada no MoodleDocs{% endif %}
+        </span>
+      </div>
+
+      {# Right-side tools: Header Search & Dark Mode Toggle #}
+      <div class="moodle-header-tools">
+        <form action="{{ pathto('search') }}" method="get" class="moodle-header-search">
+          <input type="text" name="q" placeholder="Buscar..." aria-label="Buscar na documentação" required />
+          <input type="hidden" name="check_keywords" value="yes" />
+          <input type="hidden" name="area" value="default" />
+          <button type="submit" title="Buscar">🔍</button>
+        </form>
+
+        {% if theme_enable_dark_mode|tobool %}
+          <button id="theme-toggle" class="theme-toggle-btn" aria-label="Alternar modo claro/escuro" title="Alternar modo claro/escuro">
+            <span id="theme-toggle-icon">🌙</span>
+          </button>
+        {% endif %}
+      </div>
+    </div>
+  </header>
+
+  {# 2. Sub-Header Banner Strip (Estilo barra de contexto do MoodleDocs) #}
+  <section class="moodle-sub-header">
+    <div class="moodle-sub-header-inner">
+      <div class="moodle-sub-header-title">
+        <span>Documentação</span>
+        {% if release %}
+          <span class="moodle-version-badge">v{{ release }}</span>
+        {% endif %}
+      </div>
+      <div>
+        {% if theme_github_url %}
+          <a href="{{ theme_github_url }}" class="moodle-sub-header-link" target="_blank" rel="noopener noreferrer">Repositório no GitHub ↗</a>
+        {% endif %}
+      </div>
+    </div>
+  </section>
+{% endblock %}
+
+{% block content %}
+  {# 3. Main Layout Container (Artigo na ESQUERDA, Navegação na DIREITA, como no docs.moodle.org) #}
+  <div class="moodle-main-container">
+    {# Main Article Content (Esquerda) #}
+    <main class="moodle-content" role="main">
+      {% block body %}{% endblock %}
+    </main>
+
+    {# Sidebar Navegação (DIREITA - Estilo MoodleDocs) #}
+    {% block sidebar1 %}
+      <aside class="moodle-sidebar" id="moodle-sidebar" role="navigation" aria-label="Navegação Principal">
+        {% if theme_navigation_links %}
+          <div class="moodle-sidebar-section-title">Seções &amp; Links</div>
+          <nav>
+            <ul>
+              {% if theme_navigation_links is string %}
+                {% for item in theme_navigation_links.split(',') %}
+                  {% set parts = item.strip().split('|') %}
+                  {% set title = parts[0].strip() %}
+                  {% set target = parts[1].strip() if parts|length > 1 else master_doc %}
+                  <li class="{% if pagename in target or (target == master_doc and pagename == master_doc) %}current{% endif %}">
+                    {% if target.startswith('http://') or target.startswith('https://') %}
+                      <a href="{{ target }}" target="_blank" rel="noopener noreferrer">{{ title }} ↗</a>
+                    {% else %}
+                      {% set clean_target = target[:-5] if target.endswith('.html') else target %}
+                      <a href="{{ pathto(clean_target) }}" class="{% if pagename == clean_target %}current{% endif %}">{{ title }}</a>
+                    {% endif %}
+                  </li>
+                {% endfor %}
+              {% endif %}
+            </ul>
+          </nav>
+        {% endif %}
+      </aside>
+    {% endblock %}
+  </div>
+{% endblock %}
+
+{% block footer %}
+  {# Footer #}
+  <footer class="moodle-footer" role="contentinfo">
+    <div class="moodle-footer-inner">
+      <div>
+        {% if copyright %}
+          &copy; {{ copyright }}.
+        {% else %}
+          &copy; {{ last_updated_year if last_updated_year else '' }} {{ project }}.
+        {% endif %}
+        {% if theme_footer_custom_text %}
+          {{ theme_footer_custom_text }}
+        {% endif %}
+      </div>
+      <div>
+        Desenvolvido com inspiração na documentação oficial do
+        <a href="https://docs.moodle.org/" target="_blank" rel="noopener noreferrer">MoodleDocs</a> &amp;
+        <a href="https://www.sphinx-doc.org/" target="_blank" rel="noopener noreferrer">Sphinx</a>.
+      </div>
+      {% if theme_github_url %}
+        <div>
+          <a href="{{ theme_github_url }}" target="_blank" rel="noopener noreferrer">Ver código no GitHub</a>
+        </div>
+      {% endif %}
+    </div>
+  </footer>
+</div> {# End site wrapper #}
+{% endblock %}

moodle_docs_theme/page.html

@@ -0,0 +1,7 @@
+{% extends "layout.html" %}
+
+{% block body %}
+  <article class="moodle-page">
+    {{ body }}
+  </article>
+{% endblock %}

moodle_docs_theme/searchbox.html

@@ -0,0 +1,9 @@
+{# Searchbox component for moodle_docs_theme #}
+<div class="moodle-searchbox" role="search">
+  <div class="moodle-sidebar-section-title">Buscar</div>
+  <form action="{{ pathto('search') }}" method="get">
+    <input type="text" name="q" placeholder="Buscar na documentação..." aria-label="Buscar na documentação" required />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>