eduNEXT · felipemontoya · Jul 28, 2026 · Jul 28, 2026
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -1,4 +1,7 @@
 Changelog
-=========
+#########
+
+The project `CHANGELOG.rst <../CHANGELOG.rst>`_ is included below when this
+page is built with Sphinx.
 
 .. include:: ../CHANGELOG.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -109,8 +109,10 @@ def get_version(*file_paths):
 #
 # source_encoding = 'utf-8-sig'
 
-# The top level toctree document.
-top_level_doc = 'index'
+# The document holding the root toctree. It is not `index` because every other
+# page is written to render in the GitHub interface, where `toctree` is not a
+# known directive. See docs/contents.rst.
+root_doc = 'contents'
 
 # Set display_github to False if you don't want "edit on Github" button
 html_context = {
@@ -368,7 +370,7 @@ def get_version(*file_paths):
 #  author, documentclass [howto, manual, or own class]).
 latex_target = f'{project}.tex'
 latex_documents = [
-    (top_level_doc, latex_target, documentation_title,
+    (root_doc, latex_target, documentation_title,
      author, 'manual'),
 ]
 
@@ -410,7 +412,7 @@ def get_version(*file_paths):
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (top_level_doc, project_title, documentation_title,
+    (root_doc, project_title, documentation_title,
      [author], 1)
 ]
 
@@ -425,7 +427,7 @@ def get_version(*file_paths):
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (top_level_doc, project_title, documentation_title,
+    (root_doc, project_title, documentation_title,
      author, project_title, 'A experimental plugin for Open edX designed to explore AI extensibility',
      'Miscellaneous'),
 ]

diff --git a/docs/contents.rst b/docs/contents.rst
@@ -0,0 +1,44 @@
+.. This is the Sphinx root document. It exists only to hold the toctree that
+   Sphinx needs to build the navigation.
+
+   Every other page in this directory is written so that it renders correctly
+   in the GitHub web interface, which uses plain docutils: ``toctree``,
+   ``:doc:`` and ``:ref:`` are Sphinx-only and show up there as error blocks,
+   so pages cross-link each other with ordinary relative links to ``.rst``
+   files instead. Keep this file as the single exception, and add new pages to
+   the toctree below.
+
+Documentation Contents
+######################
+
+.. toctree::
+   :maxdepth: 2
+
+   index
+   readme
+   getting_started
+   quickstarts/index
+   concepts/index
+   how-tos/index
+   how-tos/generate_badges_with_dcc_models
+   testing
+   internationalization
+   openedx_ai_badges
+   changelog
+   decisions
+   references/index
+   references/mit_slm_orchestrator
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   decisions/*
+
+
+Indices and tables
+##################
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/decisions.rst b/docs/decisions.rst
@@ -1,12 +1,9 @@
 Decisions
 #########
 
-The following `ADRs` are a record of all decisions made as a part of developing this library.
+The following `ADRs`_ are a record of all decisions made as a part of developing this library.
 
 .. _ADRs: https://open-edx-proposals.readthedocs.io/en/latest/oep-0019-bp-developer-documentation.html#adrs
 
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   decisions/*
+* `About these records <decisions/README.rst>`_
+* `0001 Offloading the AI engine to openedx-ai-extensions <decisions/0001-offload-to-ai-extensions.rst>`_
diff --git a/docs/how-tos/generate_badges_with_dcc_models.rst b/docs/how-tos/generate_badges_with_dcc_models.rst
@@ -26,7 +26,7 @@ This plugin builds on top of `openedx-ai-extensions
 installed and configured first. Follow the `AI Extensions documentation
 <https://docs.openedx.org/projects/openedx-ai-extensions/en/latest/index.html>`_,
 then install this plugin as described in the installation section of the
-:doc:`README <../readme>`::
+`README <../../README.rst>`_::
 
     pip install git+https://github.com/openedx/openedx-ai-badges.git
     tutor plugins enable openedx-ai-badges
@@ -61,7 +61,8 @@ setting rather than a Tutor variable; override it only if the service runs
 somewhere else.
 
 For the full service architecture, hosting options, and the complete list
-of configuration variables, see :doc:`../references/mit_slm_orchestrator`.
+of configuration variables, see `MIT SLM Orchestrator
+<../references/mit_slm_orchestrator.rst>`_.
 
 
 Step 1: Create the AI workflow profile
@@ -95,7 +96,7 @@ Select *Add* and fill in:
        Patch (RFC 7386) — comments and trailing commas allowed — applied
        on top of the base template.
 
-.. image:: /_static/admin-workflow-profile.png
+.. image:: ../_static/admin-workflow-profile.png
    :alt: Django admin form for an AI workflow profile using the mit_dcc_badges template
    :width: 100%
 
@@ -143,7 +144,7 @@ Select *Add* and fill in:
    * - **Enabled**
      - Checked.
 
-.. image:: /_static/admin-workflow-scope.png
+.. image:: ../_static/admin-workflow-scope.png
    :alt: Django admin form for an AI workflow scope pointing at the badges UI slot
    :width: 100%
 
@@ -163,19 +164,19 @@ Studio access to the course.
 
 Open Studio and select a course.
 
-.. image:: /_static/studio-home-course-list.png
+.. image:: ../_static/studio-home-course-list.png
    :alt: Studio home listing the available courses
    :width: 100%
 
 From the course, open **Content > Pages & Resources**.
 
-.. image:: /_static/studio-content-pages-resources.png
+.. image:: ../_static/studio-content-pages-resources.png
    :alt: The Content menu in Studio with Pages and Resources highlighted
    :width: 100%
 
 Scroll to the **AI Extensions Settings** card and select it.
 
-.. image:: /_static/pages-resources-ai-extensions-card.png
+.. image:: ../_static/pages-resources-ai-extensions-card.png
    :alt: The AI Extensions Settings card in Pages and Resources
    :width: 100%
 
@@ -184,7 +185,7 @@ already generated for the course. The message under the introduction comes
 from the profile's ``customMessage``, so it tells you which workflow is
 active — useful when several profiles are in play.
 
-.. image:: /_static/ai-badges-tab-gallery.png
+.. image:: ../_static/ai-badges-tab-gallery.png
    :alt: The AI Badges tab showing the gallery of generated badges
    :width: 100%
 

diff --git a/docs/how-tos/index.rst b/docs/how-tos/index.rst
@@ -1,7 +1,4 @@
 How-tos
 #######
 
-.. toctree::
-   :maxdepth: 1
-
-   generate_badges_with_dcc_models
+* `Generate Badges with the MIT DCC Models <generate_badges_with_dcc_models.rst>`_
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,34 +1,23 @@
-.. documentation top level file, created by
-   sphinx-quickstart on Fri Apr 11 10:00:56 2025.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Open edX AI Badges
-==================
-
-A sample backend plugin for the Open edX Platform
-
-Contents:
-
-.. toctree::
-   :maxdepth: 2
-
-   readme
-   getting_started
-   quickstarts/index
-   concepts/index
-   how-tos/index
-   testing
-   internationalization
-   openedx_ai_badges
-   changelog
-   decisions
-   references/index
-
-
-Indices and tables
 ##################
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+A backend plugin for the Open edX Platform that generates Open Badges 3.0
+definitions from course content.
+
+Contents
+********
+
+* `Overview and installation <../README.rst>`_
+* `Getting started <getting_started.rst>`_
+* `Quick start <quickstarts/index.rst>`_
+* `Concepts <concepts/index.rst>`_
+* `How-tos <how-tos/index.rst>`_
+* `Testing <testing.rst>`_
+* `Internationalization <internationalization.rst>`_
+* `Changelog <../CHANGELOG.rst>`_
+* `Architecture decisions <decisions.rst>`_
+* `References <references/index.rst>`_
+
+The Python API reference lives in the ``openedx_ai_badges*.rst`` files of this
+directory. Those are generated by ``sphinx-apidoc`` and only render once the
+documentation is built with Sphinx (``make -C docs html``).
diff --git a/docs/readme.rst b/docs/readme.rst
@@ -1 +1,7 @@
+Readme
+######
+
+The project `README.rst <../README.rst>`_ is included below when this page is
+built with Sphinx.
+
 .. include:: ../README.rst
diff --git a/docs/references/index.rst b/docs/references/index.rst
@@ -1,7 +1,4 @@
 References
 ##########
 
-.. toctree::
-   :maxdepth: 1
-
-   mit_slm_orchestrator
+* `MIT SLM Orchestrator <mit_slm_orchestrator.rst>`_