openedx · ormsbee · May 4, 2026 · May 1, 2026 · May 1, 2026 · May 1, 2026
diff --git a/README.rst b/README.rst
@@ -1,13 +1,13 @@
-Open edX Core: Foundational Packages for a Teaching & Learning Platform
-=======================================================================
+Open edX Core
+=============
 
 |pypi-badge| |ci-badge| |codecov-badge| |doc-badge| |pyversions-badge|
 |license-badge|
 
 Overview
 --------
 
-*Formerly known as "Learning Core" or "openedx-learning".*
+**Foundational Packages for a Teaching & Learning Platform** (*formerly known as "Learning Core" or "openedx-learning"*)
 
 The ``openedx-core`` project holds Django apps which represent core teaching & learning platform concepts.
 
@@ -31,7 +31,7 @@ Open edX Core Package Dependencies
 
 Open edX Core code should never import from ``openedx-platform``.
 
-We want to be very strict about dependency management internally as well. Please read the `.importlinter config file <.importlinter>`_ file and the `Python API Conventions ADR <docs/decisions/0016-python-public-api-conventions>`_ for more details.
+We want to be very strict about dependency management internally as well. Please read the `.importlinter config file <.importlinter>`_ file and the `Python API Conventions ADR <docs/openedx_content/decisions/0006-python-public-api-conventions>`_ for more details.
 
 
 Model Conventions

diff --git a/docs/changelog.rst b/docs/changelog.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -35,7 +35,7 @@ def get_version(*file_paths):
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 sys.path.append(REPO_ROOT)
 
-VERSION = get_version('src/openedx_core', '__init__.py')
+VERSION = get_version('../src/openedx_core', '__init__.py')
 
 # Configure Django for autodoc usage
 os.environ['DJANGO_SETTINGS_MODULE'] = 'test_settings'
@@ -109,7 +109,7 @@ def get_version(*file_paths):
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

diff --git a/docs/decisions.rst b/docs/decisions.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,23 +3,21 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Open edX Core
-=============
+.. _openedx-core-index:
 
-The boring, foundational bits of a learning platform that are hard to get right at scale. Currently being developed for content storage.
-
-Contents:
+.. include:: ../README.rst
 
 .. toctree::
    :maxdepth: 2
 
-   readme
-   getting_started
-   testing
-   internationalization
-   changelog
-   api_reference
-   decisions
+   openedx_core/getting_started
+   openedx_core/testing
+   openedx_core/internationalization
+   openedx_core/decisions/index
+
+   openedx_content/index
+   openedx_tagging/index
+   openedx_learning/index
 
 Indices and tables
 ==================

diff --git a/docs/api_reference.rst → docs/openedx_content/api_reference.rst b/docs/api_reference.rst → docs/openedx_content/api_reference.rst
@@ -1,3 +1,5 @@
+.. _openedx-content-api-reference:
+
 API Reference
 =============
 

diff --git a/docs/decisions/0002-content-flexibility.rst → ...nt/decisions/0001-content-flexibility.rst b/docs/decisions/0002-content-flexibility.rst → ...nt/decisions/0001-content-flexibility.rst
@@ -1,4 +1,6 @@
-2. Approach to Content Flexibility
+.. _openedx-content-adr-0001:
+
+1. Approach to Content Flexibility
 ==================================
 
 Status

diff --git a/.../decisions/0003-content-extensibility.rst → .../decisions/0002-content-extensibility.rst b/.../decisions/0003-content-extensibility.rst → .../decisions/0002-content-extensibility.rst
@@ -1,4 +1,6 @@
-3. Content Extensibility Through Model Relations
+.. _openedx-content-adr-0002:
+
+2. Content Extensibility Through Model Relations
 ================================================
 
 Context

diff --git a/...decisions/0005-identifier-conventions.rst → ...decisions/0003-identifier-conventions.rst b/...decisions/0005-identifier-conventions.rst → ...decisions/0003-identifier-conventions.rst
@@ -1,4 +1,6 @@
-5. Identifier Conventions
+.. _openedx-content-adr-0003:
+
+3. Identifier Conventions
 =========================
 
 Status

diff --git a/docs/decisions/0006-app-label-prefix.rst → ...ntent/decisions/0004-app-label-prefix.rst b/docs/decisions/0006-app-label-prefix.rst → ...ntent/decisions/0004-app-label-prefix.rst
@@ -1,10 +1,12 @@
-6. App Label Prefix
+.. _openedx-content-adr-0004:
+
+4. App Label Prefix
 ===================
 
 Status
 ------
 
-Obsolete. See decision 0020. Apps like ``openedx_content`` no longer use the ``oel_`` prefix, and this repo is no longer called "learning core".
+Obsolete. See decision :ref:`openedx-content-adr-0010`. Apps like ``openedx_content`` no longer use the ``oel_`` prefix, and this repo is no longer called "learning core".
 
 Context
 -------

diff --git a/.../decisions/0015-serving-static-assets.rst → .../decisions/0005-serving-static-assets.rst b/.../decisions/0015-serving-static-assets.rst → .../decisions/0005-serving-static-assets.rst
@@ -1,4 +1,6 @@
-15. Serving Course Team Authored Static Assets
+.. _openedx-content-adr-0005:
+
+5. Serving Course Team Authored Static Assets
 ==============================================
 
 Context

diff --git a/...ns/0016-python-public-api-conventions.rst → ...ns/0006-python-public-api-conventions.rst b/...ns/0016-python-public-api-conventions.rst → ...ns/0006-python-public-api-conventions.rst
@@ -1,10 +1,12 @@
-16. Python Public API Conventions
+.. _openedx-content-adr-0006:
+
+6. Python Public API Conventions
 =================================
 
 Status
 ------
 
-Superseded by decision 0020.
+Superseded by decision :ref:`openedx-content-adr-0010`.
 
 Context
 --------

diff --git a/...decisions/0017-generalized-containers.rst → ...decisions/0007-generalized-containers.rst b/...decisions/0017-generalized-containers.rst → ...decisions/0007-generalized-containers.rst
@@ -1,4 +1,6 @@
-17. Modeling Containers as a Generalized Capability for Holding Content
+.. _openedx-content-adr-0007:
+
+7. Modeling Containers as a Generalized Capability for Holding Content
 ========================================================================
 
 Status
@@ -50,8 +52,8 @@ This section defines container types, content constraints, hierarchy, and extens
 - Containers can be nested within other containers, allowing for complex content structures. For example, subsections can contain units.
 - Containers might be of different types, with each type potentially having different restrictions on the type of content it can hold but that will not be enforced by containers.
 - Content restrictions for containers are implemented at the app layer, allowing specific container types, like units, to limit their children to particular content types, e.g., units are restricted to contain only components.
-- The course hierarchy Course > Section > Subsection > Unit will be implemented as relationships between containers, with each level acting as a container that holds other content. The hierarchy will be enforced by the content restrictions of each particular container but allowed to be overridden to support `Approach to Content Flexibility <0002-content-flexibility.rst>`_.
-- Containers will follow extensibility principles in `Content Extensibility Through Model Relations <0003-content-extensibility.rst>`_ for creating new container types or subtypes.
+- The course hierarchy Course > Section > Subsection > Unit will be implemented as relationships between containers, with each level acting as a container that holds other content. The hierarchy will be enforced by the content restrictions of each particular container but allowed to be overridden to support :ref:`openedx-content-adr-0001`.
+- Containers will follow extensibility principles in :ref:`openedx-content-adr-0002` for creating new container types or subtypes.
 
 3. Container Children and Relationships
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/decisions/0018-units-as-containers.rst → ...nt/decisions/0008-units-as-containers.rst b/docs/decisions/0018-units-as-containers.rst → ...nt/decisions/0008-units-as-containers.rst
@@ -1,4 +1,6 @@
-18. Modeling Units as a Concrete Implementation of the Container Capability
+.. _openedx-content-adr-0008:
+
+8. Modeling Units as a Concrete Implementation of the Container Capability
 ===========================================================================
 
 Context
@@ -9,7 +11,7 @@ The container capability is a generalized capability to hold different types of
 Decisions
 ---------
 
-All decisions from `0017-generalized-containers.rst <0017-generalized-containers.rst>`_ are still valid but are written here alongside unit-specific decisions for better illustration.
+All decisions from :ref:`openedx-content-adr-0007` are still valid but are written here alongside unit-specific decisions for better illustration.
 
 1. Units as Containers
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -25,7 +27,7 @@ All decisions from `0017-generalized-containers.rst <0017-generalized-containers
 - Units can only hold components as their children but will not enforce this restriction at the model level.
 - Units are the first level of nested content types Unit > Components.
 - Content restrictions for units are implemented at the application layer, allowing units to limit their children to only components. None of this is enforced at the model level.
-- Unit subtypes can be created by following the extensibility principles in `Content Extensibility Through Model Relations <0003-content-extensibility.rst>`_.
+- Unit subtypes can be created by following the extensibility principles in :ref:`openedx-content-adr-0002`.
 
 3. Unit Children and Relationships
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/decisions/0019-selectors.rst → ...nedx_content/decisions/0009-selectors.rst b/docs/decisions/0019-selectors.rst → ...nedx_content/decisions/0009-selectors.rst
@@ -1,4 +1,6 @@
-19. Selectors for Dynamically Selecting Content
+.. _openedx-content-adr-0009:
+
+9. Selectors for Dynamically Selecting Content
 ===============================================
 
 Status
@@ -35,7 +37,7 @@ This section explains the concepts and behaviors used to build dynamic selection
 
 This section describes how different types of selectors work and how they handle the selection of dynamic content.
 
-- A selector can be of any type, which means it can implement any method to select members from a pool. Therefore, selectors will follow extensibility principles in `0003-content-extensibility.rst <0003-content-extensibility.rst>`_ for creating new selector types.
+- A selector can be of any type, which means it can implement any method to select members from a pool. Therefore, selectors will follow extensibility principles in :ref:`openedx-content-adr-0002` for creating new selector types.
 - Selection versions encode the rules and holds useful details for the selection process like: where to get members from, number of items to select, and other criteria. For instance, for the "select 5 components out of this pool of 20 components" its selector version would encode where to get the 20 components, how many to get for each user and any other detail needed to create the specific variants.
 - Depending on the size of the pool of members, variants can be generated at publishing time or on-demand. This behavior should be determined by the selector version based on high vs low permutation scenarios.
 - A compositor is responsible for populating the variants but will not be implemented as part of the selector application which belongs to the authoring app.

diff --git a/...e-authoring-apps-into-openedx-content.rst → ...e-authoring-apps-into-openedx-content.rst b/...e-authoring-apps-into-openedx-content.rst → ...e-authoring-apps-into-openedx-content.rst
@@ -1,4 +1,6 @@
-20. Merge authoring apps into openedx_content (using Applets)
+.. _openedx-content-adr-0010:
+
+10. Merge authoring apps into openedx_content (using Applets)
 =============================================================
 
 Context
@@ -50,7 +52,7 @@ We are going to take advantage of the fact that these two can be separated using
 
 There are a few high level constraints that we have to consider:
 
-#. Existing openedx-platform migrations should not be modified. Existing openedx-platform migrations should remain unchanged. This is important to make sure that we do not introduce ordering inconsistencies for sites that have already run migrations for the old apps and are upgrading to a new release (e.g. Verawood).
+#. Existing openedx-platform migrations should not be modified. This is important to make sure that we do not introduce ordering inconsistencies for sites that have already run migrations for the old apps and are upgrading to a new release (e.g. Verawood).
 #. The openedx-learning repo should not have any dependencies on openedx-platform migrations, because our dependencies strictly go in the other direction: openedx-platform calls openedx-learning, not the other way around. Furthermore, openedx-learning will often be run without openedx-platform, such as for local development or during CI.
 #. Two of the openedx-platform apps that have foreign keys to openedx-learning models are only in Studio's INSTALLED_APPS (``contentstore`` and ``modulestore_migrator``), while ``content_libraries`` is installed in both Studio and LMS. Migrations may be run for LMS or Studio first, depending on the user and environment. Tutor runs LMS first, but we can't assume that will always be true.
 #. We must support people who are installing from scratch, those who are upgrading from the Ulmo release, as well as those who are running off of the master branch of openedx-platform.
@@ -66,7 +68,7 @@ Therefore, the migrations will happen in the following order:
 
 The tricky part is that all the ``opendx-learning`` migrations will run before any of the ``openedx-platform`` migrations run. We can't force it to do otherwise without making ``openedx-learning`` aware of ``opendx-platform``, and we explicitly want to avoid that. This makes things tricky with respect to the model state dependencies. There are two scenarios we have to worry about:
 
-Migration from Scrach
+Migration from Scratch
   The ``openedx-platform`` apps will each run the squashed migration that jumps straight to making foreign keys against the new ``openedx_content`` models, so the fact that the old authoring app models have been removed and the tables have been renamed doesn't matter.
 
 Migration from Ulmo/master

diff --git a/docs/openedx_content/decisions/index.rst b/docs/openedx_content/decisions/index.rst
@@ -0,0 +1,12 @@
+.. _openedx-content-decisions-index:
+
+Decisions
+=========
+
+Architecture Decision Records for the ``openedx_content`` app.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *
diff --git a/docs/openedx_content/index.rst b/docs/openedx_content/index.rst
@@ -0,0 +1,12 @@
+.. _openedx-content-index:
+
+openedx_content
+===============
+
+Django app for modeling and authoring course content structures.
+
+.. toctree::
+   :maxdepth: 1
+
+   decisions/index
+   api_reference
diff --git a/docs/public_apis/content_api.rst → ...enedx_content/public_apis/content_api.rst b/docs/public_apis/content_api.rst → ...enedx_content/public_apis/content_api.rst
@@ -1,3 +1,5 @@
+.. _openedx-content-api:
+
 Content API
 ===========
 

diff --git a/docs/public_apis/content_models.rst → ...dx_content/public_apis/content_models.rst b/docs/public_apis/content_models.rst → ...dx_content/public_apis/content_models.rst
@@ -1,3 +1,5 @@
+.. _openedx-content-models-api:
+
 Content Models
 ==============
 

diff --git a/docs/decisions/0001-purpose-of-this-repo.rst → ...e/decisions/0001-purpose-of-this-repo.rst b/docs/decisions/0001-purpose-of-this-repo.rst → ...e/decisions/0001-purpose-of-this-repo.rst
@@ -1,3 +1,5 @@
+.. _openedx-core-adr-0001:
+
 1. Purpose of this Repo
 =======================
 

diff --git a/docs/decisions/0021-openedx-core.rst → ...nedx_core/decisions/0002-openedx-core.rst b/docs/decisions/0021-openedx-core.rst → ...nedx_core/decisions/0002-openedx-core.rst
@@ -1,4 +1,6 @@
-21. Learning Core is now Open edX Core
+.. _openedx-core-adr-0002:
+
+2. Learning Core is now Open edX Core
 ======================================
 
 Context
@@ -47,8 +49,8 @@ We'll implement this change immediately as detailed in https://github.com/opened
 Rejected alternatives
 ---------------------
 
-* Separate repos for ``openedx-content``, ``openedx-cbe``, etc. 
-  
+* Separate repos for ``openedx-content``, ``openedx-cbe``, etc.
+
   * Axim is making a conscious effort to slow the proliferation of new repos, as it has been challenging to maintain consistent standards, tooling, and upgrades across all of them. If there is not a strong reason to separate repos, then we would prefer to start off with a single repo.
 
 * A combined top level Python package with nested apps: ``openedx_core.content.api``, ``openedx_core.cbe.api``, etc.

diff --git a/docs/openedx_core/decisions/index.rst b/docs/openedx_core/decisions/index.rst
@@ -0,0 +1,12 @@
+.. _openedx-core-decisions-index:
+
+Decisions
+=========
+
+Architecture Decision Records relating to the overall openedx-core repository.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *
diff --git a/docs/getting_started.rst → docs/openedx_core/getting_started.rst b/docs/getting_started.rst → docs/openedx_core/getting_started.rst
@@ -1,3 +1,5 @@
+.. _openedx-core-getting-started:
+
 Getting Started
 ===============
 

diff --git a/docs/internationalization.rst → docs/openedx_core/internationalization.rst b/docs/internationalization.rst → docs/openedx_core/internationalization.rst
diff --git a/docs/testing.rst → docs/openedx_core/testing.rst b/docs/testing.rst → docs/openedx_core/testing.rst