From e65ec93e691f6160f270c25933de8f210c6f2460 Mon Sep 17 00:00:00 2001 From: Felipe Montoya Date: Tue, 28 Jul 2026 12:05:20 -0500 Subject: [PATCH] feat: fixing the relative paths to images when rendering in gh --- docs/changelog.rst | 5 +- docs/conf.py | 12 +++-- docs/contents.rst | 44 ++++++++++++++++ docs/decisions.rst | 9 ++-- .../generate_badges_with_dcc_models.rst | 17 ++++--- docs/how-tos/index.rst | 5 +- docs/index.rst | 51 ++++++++----------- docs/readme.rst | 6 +++ docs/references/index.rst | 5 +- 9 files changed, 95 insertions(+), 59 deletions(-) create mode 100644 docs/contents.rst diff --git a/docs/changelog.rst b/docs/changelog.rst index 4de03af..c27539f 100644 --- 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 index e20ce3f..f285fbc 100644 --- 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 new file mode 100644 index 0000000..6f2e2d4 --- /dev/null +++ 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 index a21903c..a742794 100644 --- 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 `_ +* `0001 Offloading the AI engine to openedx-ai-extensions `_ diff --git a/docs/how-tos/generate_badges_with_dcc_models.rst b/docs/how-tos/generate_badges_with_dcc_models.rst index 2913339..f520bad 100644 --- 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 `_, 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 index ecaebb8..66dbc4c 100644 --- 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 `_ diff --git a/docs/index.rst b/docs/index.rst index 84f3300..cd83891 100644 --- 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 `_ +* `Quick start `_ +* `Concepts `_ +* `How-tos `_ +* `Testing `_ +* `Internationalization `_ +* `Changelog <../CHANGELOG.rst>`_ +* `Architecture decisions `_ +* `References `_ + +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 index 72a3355..7f960f2 100644 --- 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 index 1b5c56a..ba4791d 100644 --- a/docs/references/index.rst +++ b/docs/references/index.rst @@ -1,7 +1,4 @@ References ########## -.. toctree:: - :maxdepth: 1 - - mit_slm_orchestrator +* `MIT SLM Orchestrator `_