Skip to content

chore: Add references to docs to make relative, not direct, references #716

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

chore: Add references to docs to make relative, not direct, references #716

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a7a3fa6
chore: Add references to docs to make relative, not direct, references
sarina Jun 8, 2025
c7b1610
chore: Convert internal `:doc:` directives to `:ref:`s
sarina Jun 8, 2025
30a1cab
chore: Convert OEP headers to use `:ref:` instead of `:doc:`
sarina Jun 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion oep-templates/adr-based-template.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

.. Below is the display in the left sidebar on RTD. Please omit leading 0's

.. _OEP-XXXX OEP Template:

OEP-XXXX: OEP Template
######################

Expand All @@ -13,7 +15,7 @@ OEP-XXXX: OEP Template
* - OEP
- Link to the doc in the following format::

:doc:`OEP-XXXX <oep-XXXX-YYYY-ZZZZ>`
:ref:`OEP-XXXX OEP Template`

* <XXXX is the next available OEP number>
* <YYYY is the abbreviated Type: proc | bp | arch>
Expand Down
4 changes: 3 additions & 1 deletion oep-templates/external-link-template.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

.. Below is the display in the left sidebar on RTD. Please omit leading 0's

.. _OEP XXXX OEP Template:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure why sphinx is not complaining about this, this label has been defined twice also it's only different from the label in oep-templates/adr-based-template.rst by one dash. Are these template files not processed by default or something?

Copy link
Contributor Author

@sarina sarina Jun 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The top-level oep-templates directory is not processed in the build, the top-level oeps directory is considered the source dir.


OEP-XXXX: OEP Template
######################

Expand All @@ -13,7 +15,7 @@ OEP-XXXX: OEP Template
* - OEP
- Link to the doc in the following format::

:doc:`OEP-XXXX <oep-XXXX-YYYY-ZZZZ>`
:ref:`OEP-XXXX OEP Template`

* <XXXX is the next available OEP number>
* <YYYY is the abbreviated Type: proc | bp | arch>
Expand Down
4 changes: 3 additions & 1 deletion oep-templates/pep-based-template.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

.. Below is the display in the left sidebar on RTD. Please omit leading 0's

.. _OEP XXXX OEP Template:

OEP-XXXX: OEP Template
######################

Expand All @@ -13,7 +15,7 @@ OEP-XXXX: OEP Template
* - OEP
- Link to the doc in the following format::

:doc:`OEP-XXXX <oep-XXXX-YYYY-ZZZZ>`
:ref:`OEP-XXXX OEP Template`

* <XXXX is the next available OEP number>
* <YYYY is the abbreviated Type: proc | bp | arch>
Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0003-arch-async-tasks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
.. _OEP-3 Asynchronous Task Management:

OEP-3: Asynchronous Task Management
###################################

+---------------+-------------------------------------------+
| OEP | :doc:`oep-0003-arch-async-tasks` |
| OEP | :ref:`OEP-3 Asynchronous Task Management` |
+---------------+-------------------------------------------+
| Title | Asynchronous Task Management |
+---------------+-------------------------------------------+
Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0004-arch-oauth-scopes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
.. _OEP-4 Application Authorization (Scopes):

OEP-4: Application Authorization (Scopes)
#########################################

.. list-table::
:widths: 25 75

* - OEP
- :doc:`OEP-4 <oep-0004-arch-oauth-scopes>`
- :ref:`OEP-4 Application Authorization (Scopes)`
* - Title
- Application Authorization (Scopes)
* - Last Modified
Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0015-arch-course-wide-js.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
.. _OEP-15 Course-wide Custom JavaScript:

OEP-15: Course-wide Custom JavaScript
#####################################

+---------------+----------------------------------------------------+
| OEP | :doc:`OEP-15 <oep-0015-arch-course-wide-js>` |
| OEP | :ref:`OEP-15 Course-wide Custom JavaScript` |
+---------------+----------------------------------------------------+
| Title | Course-wide Custom JavaScript |
+---------------+----------------------------------------------------+
Expand Down
6 changes: 4 additions & 2 deletions oeps/architectural-decisions/oep-0026-arch-realtime-events.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
.. _OEP-26 Real-time Events:

OEP-26: Real-time Events
##########################

+-----------------+--------------------------------------------------------+
| OEP | :doc:`OEP-26 <oep-0026-arch-realtime-events>` |
| OEP | :ref:`OEP-26 Real-time Events` |
+-----------------+--------------------------------------------------------+
| Title | Real-time Events |
+-----------------+--------------------------------------------------------+
Expand Down Expand Up @@ -35,7 +37,7 @@ Status

As of 2025-02-05, this OEP has been accepted. It has been implemented in Open edX as the `event_routing_backends`_ plugin, which is currently in use for delivering real-time analytics to Aspects and to deliver real-time events to external systems via xAPI and Caliper. While that project adheres closely to this OEP, there are also other event-based communication mechanisms within the platform that are covered by other OEPs.

`OEP-41 <oep-0041-arch-async-server-event-messaging>`_ and `OEP-52 <oep-0052-arch-event-bus-architecture>`_ cover the general format and conventions for generic asynchronous event messaging across and within services. While this OEP concerns itself learner-specific event sharing. There is also some overlap, for instance when event-routing-backends is configured to send events to an event bus, however this OEP is not considered superceded at this time.
:ref:`OEP-41 <OEP-41 Asynchronous Server Event Message Format>` and :ref:`OEP-52 <oep-52>` cover the general format and conventions for generic asynchronous event messaging across and within services. While this OEP concerns itself learner-specific event sharing. There is also some overlap, for instance when event-routing-backends is configured to send events to an event bus, however this OEP is not considered superceded at this time.

Where possible this document has been updated to match the implemented reality. However some sections may be out of date. The `event_routing_backends`_ plugin is the authoritative source for the current implementation.

Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0030-arch-pii-markup-and-auditing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
.. _OEP-30 PII Markup and Auditing:

OEP-30: PII Markup and Auditing
###############################

+---------------+------------------------------------------------------------+
| OEP | :doc:`OEP-30 <oep-0030-arch-pii-markup-and-auditing>` |
| OEP | :ref:`OEP-30 PII Markup and Auditing` |
+---------------+------------------------------------------------------------+
| Title | Personally Identifiable Information Markup and Auditing |
+---------------+------------------------------------------------------------+
Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0031-arch-i18n.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
.. _OEP-31 Micro-frontend Internationalization:

OEP-31: Micro-frontend Internationalization
###########################################

.. list-table::

* - OEP
- :doc:`OEP-31 <oep-0031-arch-i18n>`
- :ref:`OEP-31 Micro-frontend Internationalization`
* - Title
- Micro-frontend Internationalization
* - Last Modified
Expand Down
7 changes: 4 additions & 3 deletions oeps/architectural-decisions/oep-0032-arch-unique-identifier-for-users.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
.. _oep-32:
.. _OEP-32 Unique Identifier for Users:

OEP-32: Unique Identifier for Users
###################################
Expand All @@ -7,7 +8,7 @@ OEP-32: Unique Identifier for Users
:widths: 25 75

* - OEP
- :doc:`OEP-32 <oep-0032-arch-unique-identifier-for-users>`
- :ref:`OEP-32 <OEP-32 Unique Identifier for Users>`
* - Title
- Unique Identifier for Users
* - Last Modified
Expand Down Expand Up @@ -42,7 +43,7 @@ The *LMS user_id* should be used for all internal events. Additionally, the *LMS

.. warning::

A new external user id should still be used with third-parties under certain circumstances. This is especially important when the user id is sent along with other :doc:`Personally Identifiable Information (PII) <oep-0030-arch-pii-markup-and-auditing>`. See the `ADR for the edx-platform external_user_ids Django app`_ for more details.
A new external user id should still be used with third-parties under certain circumstances. This is especially important when the user id is sent along with other :ref:`Personally Identifiable Information (PII) <OEP-30 PII Markup and Auditing>`. See the `ADR for the edx-platform external_user_ids Django app`_ for more details.

.. _Django auth_user: https://docs.djangoproject.com/en/2.0/topics/auth/default/#user-objects
.. _ADR for the edx-platform external_user_ids Django app: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/external_user_ids/docs/decisions/0001-externalid.rst
Expand All @@ -66,7 +67,7 @@ The requirements for a User Identifier are as follows:

* The identifier for a given user should not change.

* The identifier should not contain :doc:`Personally Identifiable Information (PII) <oep-0030-arch-pii-markup-and-auditing>`.
* The identifier should not contain :ref:`Personally Identifiable Information (PII) <OEP-30 PII Markup and Auditing>`.

* The identifier should be consistent across all systems, including the LMS and Studio, mobile apps for iOS and Android, and other Open edX Services like Ecommerce.

Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0041-arch-async-server-event-messaging.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
.. _OEP-41 Asynchronous Server Event Message Format:

OEP-41: Asynchronous Server Event Message Format
################################################

.. list-table::
:widths: 25 75

* - OEP
- :doc:`OEP-41 <oep-0041-arch-async-server-event-messaging>`
- :ref:`OEP-41 Asynchronous Server Event Message Format`
* - Title
- Asynchronous Server Event Message Format
* - Last Modified
Expand Down
6 changes: 4 additions & 2 deletions oeps/architectural-decisions/oep-0045-arch-ops-and-config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
.. _OEP-45 Configuring and Operating Open edX:

OEP-45: Configuring and Operating Open edX
##########################################

.. list-table::
:widths: 25 75

* - OEP
- :doc:`OEP-0045 <oep-0045-arch-ops-and-config>`
- :ref:`OEP-45 Configuring and Operating Open edX`
* - Title
- Configuring and Operating Open edX
* - Last Modified
Expand Down Expand Up @@ -218,4 +220,4 @@ Change History
2024-05-16
==========
* Change status to "Needs Revision"
* `Pull request #586 <https://github.com/openedx/open-edx-proposals/pull/586>`_
* `Pull request #586 <https://github.com/openedx/open-edx-proposals/pull/586>`_
2 changes: 2 additions & 0 deletions ...ecisions/oep-0045/decisions/0001-tutor-as-replacement-for-edx-configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _Tutor as a replacement for edx/configuration:

Tutor as a replacement for ``edx/configuration``
################################################

Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0048-brand-customization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
.. _OEP-48 Brand Customization:

OEP-48: Brand Customization
###########################

.. list-table::
:widths: 25 75

* - OEP
- :doc:`OEP-0048 <oep-0048-brand-customization>`
- :ref:`OEP-48 Brand Customization`
* - Title
- Brand Customization
* - Last Modified
Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0050-hooks-extension-framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
.. _OEP-50 Hooks extension framework:

OEP-50: Hooks extension framework
#################################

.. list-table::
:widths: 25 75

* - OEP
- :doc:`OEP-0050 <oep-0050-hooks-extension-framework>`
- :ref:`OEP-50 Hooks extension framework`
* - Title
- Open edX Hooks Extension Framework
* - Last Modified
Expand Down
5 changes: 3 additions & 2 deletions oeps/architectural-decisions/oep-0052-arch-event-bus-architecture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
.. _oep-52:
.. _OEP-52 Event Bus Architecture:

OEP-52: Event Bus Architecture
##############################
Expand All @@ -9,7 +10,7 @@ OEP-52: Event Bus Architecture
:widths: 25 75

* - OEP-52
- :doc:`OEP-0052 <oep-0052-arch-event-bus-architecture>`
- :ref:`OEP-52 <OEP-52 Event Bus Architecture>`
* - Title
- Event Bus Architecture
* - Last Modified
Expand Down Expand Up @@ -45,7 +46,7 @@ Overview
Context
*******

The already accepted :doc:`oep-0041-arch-async-server-event-messaging` details the general format and conventions the Open edX platform should use for asynchronous event messaging across services. It also provides background on a set of :ref:`Event Messaging Architectural Goals` for the Open edX platform, including:
The already accepted :ref:`OEP-41 Asynchronous Server Event Message Format` details the general format and conventions the Open edX platform should use for asynchronous event messaging across services. It also provides background on a set of :ref:`Event Messaging Architectural Goals` for the Open edX platform, including:

* Align with the `Architecture Manifesto`_ themes of decentralization and asynchronous communication in support of loose coupling between services.
* Eliminate blocking, synchronous requests.
Expand Down
4 changes: 3 additions & 1 deletion oeps/architectural-decisions/oep-0058-arch-translations-management.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
.. _OEP-58 Translations Management:

OEP-58: Translations Management
###############################

.. list-table::
:widths: 25 75

* - OEP
- :doc:`OEP-58 <oep-0058-arch-translations-management>`
- :ref:`OEP-58 Translations Management`
* - Title
- Translations Management
* - Last Modified
Expand Down
4 changes: 3 additions & 1 deletion ...itectural-decisions/oep-0064-arch-mobile-application-codebase-modernization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
.. _OEP-64 Mobile App Codebase Modernization:

OEP-64: Mobile App Codebase Modernization
#########################################

.. list-table::
:widths: 25 75

* - OEP
- :doc:`OEP-64 <oep-0064-arch-mobile-application-codebase-modernization>`
- :ref:`OEP-64 Mobile App Codebase Modernization`
* - Title
- Mobile Application Codebase Modernization
* - Last Modified
Expand Down
12 changes: 7 additions & 5 deletions oeps/architectural-decisions/oep-0065-arch-frontend-composability.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
.. _OEP-65 Frontend Composibility:

OEP-65: Frontend Composability
##############################

.. list-table::
:widths: 25 75

* - OEP
- :doc:`OEP-65 <oep-0065-arch-frontend-composability>`
- :ref:`OEP-65 Frontend Composibility`
* - Title
- Frontend Composability
* - Last Modified
Expand All @@ -29,10 +31,10 @@ OEP-65: Frontend Composability
* - References
- * `FC-0054 - Composable Micro-frontends Discovery <https://openedx.atlassian.net/wiki/spaces/COMM/pages/4063821827/FC-0054+-+Composable+Micro-frontends+Piral+Discovery>`_
* `FC-0007 - Modular MFE Domains Discovery <https://openedx.atlassian.net/wiki/spaces/COMM/pages/3614900241/CLOSED+FC-0007+-+Modular+MFE+Domains+Discovery>`_
* :doc:`ADR 0001 - Create a unified platform repository </architectural-decisions/oep-0065/decisions/0001-unified-platform-repository>`
* :doc:`ADR 0002 - Frontend app migrations </architectural-decisions/oep-0065/decisions/0002-frontend-app-migrations>`
* :doc:`ADR 0003 - Frontend projects </architectural-decisions/oep-0065/decisions/0003-frontend-projects>`
* :doc:`OEP-65 Frontend Glossary </architectural-decisions/oep-0065/decisions/frontend-glossary>`
* :ref:`ADR 0001 - Create a unified platform repository <Create a unified platform repository>`
* :ref:`ADR 0002 - Frontend app migrations <Frontend App Migrations>`
* :ref:`ADR 0003 - Frontend projects <Frontend Projects>`
* :ref:`OEP-65 Frontend Glossary <Frontend Glossary>`

.. contents::
:local:
Expand Down
12 changes: 7 additions & 5 deletions ...architectural-decisions/oep-0065/decisions/0001-unified-platform-repository.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _Create a unified platform repository:

Create a unified platform repository
####################################

Expand All @@ -9,7 +11,7 @@ Accepted
Summary
*******

This ADR proposes combining a number of repositories into a single, unified frontend platform library as a migration strategy for implementing :doc:`OEP-65 <../../oep-0065-arch-frontend-composability>`. This library is named `frontend-base <https://github.com/openedx/frontend-base>`_.
This ADR proposes combining a number of repositories into a single, unified frontend platform library as a migration strategy for implementing :ref:`OEP-65 <OEP-65 Frontend Composibility>`. This library is named `frontend-base <https://github.com/openedx/frontend-base>`_.

Context
*******
Expand Down Expand Up @@ -124,10 +126,10 @@ We believe this is a reasonable migration strategy given the generally low rate
References
**********

* :doc:`OEP-65: Frontend Composability <../../oep-0065-arch-frontend-composability>`
* :doc:`OEP-65 Frontend Glossary <./frontend-glossary>`
* :doc:`ADR-0002: Frontend App Migrations <./0002-frontend-app-migrations>`
* :doc:`ADR-0003: Frontend Projects <./0003-frontend-projects>`
* :ref:`OEP-65: Frontend Composability <OEP-65 Frontend Composibility>`
* :ref:`OEP-65 Frontend Glossary <Frontend Glossary>`
* :ref:`ADR-0002: Frontend App Migrations <Frontend App Migrations>`
* :ref:`ADR-0003: Frontend Projects <Frontend Projects>`

Change History
**************
Expand Down
Loading