openedx · saraburns1 · Mar 9, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 27, 2026
diff --git a/docs/Makefile b/docs/Makefile
@@ -14,6 +14,9 @@ help:
 
 .PHONY: help Makefile
 
+serve_docs: ## serve the built docs locally to preview the site in the browser
+	sphinx-autobuild source $(BUILDDIR)/html --ignore '**/_tags/*'
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile

diff --git a/...documentation/how-tos/install_aspects.rst → ...umentation/how-tos/01_install_aspects.rst b/...documentation/how-tos/install_aspects.rst → ...umentation/how-tos/01_install_aspects.rst
@@ -1,5 +1,7 @@
-Aspects Plugin for Tutor
-************************
+.. _install_aspects:
+
+Install Aspects Plugin for Tutor
+********************************
 
 Aspects is implemented as a Tutor plugin. To learn more about how to install it, please refer to the plugin GitHub site: 
 `<https://github.com/openedx/tutor-contrib-aspects?tab=readme-ov-file#installation>`_ 

diff --git a/...chnical_documentation/how-tos/upgrade.rst → ...ical_documentation/how-tos/02_upgrade.rst b/...chnical_documentation/how-tos/upgrade.rst → ...ical_documentation/how-tos/02_upgrade.rst
@@ -1,6 +1,6 @@
 .. _upgrade-aspects:
 
-How-to Upgrade Aspects
+Upgrade Aspects
 **********************
 
 Aspects is intended to have a faster upgrade cycle than Open edX named releases since operators might want to upgrade between releases to get features as they become available. The upgrade process is the same whether it's happening as part of a named release upgrade or in between.

diff --git a/...tion/how-tos/production_configuration.rst → ...-tos/aspects_production_configuration.rst b/...tion/how-tos/production_configuration.rst → ...-tos/aspects_production_configuration.rst
@@ -1,6 +1,6 @@
 .. _production_configuration:
 
-Configure Aspects for Production
+Configure Aspects for production
 ********************************
 
 Choosing an xAPI Pipeline
@@ -199,13 +199,13 @@ By default, Aspects enables plugin functionality in the LMS that embeds a define
 - ``ASPECTS_LEARNER_GROUPS_HELP_MARKDOWN`` controls the content of the "Help" tab in the At-Risk Learners dashboard
 - ``ASPECTS_OPERATOR_HELP_MARKDOWN`` controls the content of the "Help" tab in the Operator dashboard
 
-In-context Metrics
+In-Context Metrics
 ------------------
 
-Starting in the Teak Open edX release, Aspects provides in-context metrics in Studio. The following settings controls this functionality.
+Starting in the Teak Open edX release, Aspects provides :ref:`In-Context Dashboards` in Studio. Reference the `plugin <https://github.com/openedx/frontend-plugin-aspects?tab=readme-ov-file#development-setup>` for setup instructions.
 
-- ``ASPECTS_ENABLE_STUDIO_IN_CONTEXT_METRICS`` - Enables or disables in-context metrics.
-- ``ASPECTS_IN_CONTEXT_DASHBOARDS`` - A dictionary mapping block types to in-context dashboards. You can use this option to remove or replace the in-context dashboard for a block type. The key `course` defines the in-context dashboard for course overview.
+For further customization, the setting ``ASPECTS_IN_CONTEXT_DASHBOARDS`` (in `platform-plugin-aspects`_) is a dictionary mapping block types to in-context dashboards. 
+You can use this setting to remove or replace the in-context dashboard for a block type. The key `course` defines the in-context dashboard for course overview.
 
 
 Ralph Accessibility
@@ -396,3 +396,4 @@ These are also captured in the Aspects Operator Dashboard as well as a filterabl
 .. _Ralph via Helm chart: https://openfun.github.io/ralph/latest/tutorials/helm/
 .. _dump_data_to_clickhouse arguments: https://github.com/openedx/platform-plugin-aspects/blob/951ed84de01dda6bec9923c60fcd96bf80d6fa54/platform_plugin_aspects/management/commands/dump_data_to_clickhouse.py#L91
 .. _transform_tracking_logs: https://event-routing-backends.readthedocs.io/en/latest/technical_documentation/how-tos/how_to_bulk_transform.html
+.. _platform-plugin-aspects: https://github.com/openedx/platform-plugin-aspects/blob/main/platform_plugin_aspects/settings/common.py#L112
diff --git a/...ation/how-tos/troubleshooting_aspects.rst → ...ation/how-tos/aspects_troubleshooting.rst b/...ation/how-tos/troubleshooting_aspects.rst → ...ation/how-tos/aspects_troubleshooting.rst
@@ -1,6 +1,6 @@
 .. _troubleshooting_aspects:
 
-Troubleshooting Aspects
+Troubleshoot Aspects
 #######################
 
 Most common problems with Aspects can be fixed by making sure everything is up to date by deleting

diff --git a/docs/technical_documentation/how-tos/aspects_without_tutor.rst b/docs/technical_documentation/how-tos/aspects_without_tutor.rst
@@ -1,7 +1,7 @@
 .. _aspects-without-tutor:
 
-Running Aspects Without Tutor
-*****************************
+Run Aspects without Tutor
+*************************
 
 In cases where Open edX is deployed outside of the Tutor environment, setting up Aspects is quite challenging. This guide aims to present the steps needed to stand up and configure an Aspects environment using Tutor and tutor-contrib-aspects to create the resources needed to configure an Aspects environment with an existing non-Tutor deployment.
 

diff --git a/docs/technical_documentation/how-tos/backfill.rst b/docs/technical_documentation/how-tos/backfill.rst
@@ -1,3 +1,5 @@
+.. _backfill:
+
 Backfill old or missing data
 ****************************
 

diff --git a/docs/technical_documentation/how-tos/changing_actor_identifier.rst b/docs/technical_documentation/how-tos/changing_actor_identifier.rst
@@ -1,6 +1,6 @@
 .. _changing_actor_identifier:
 
-Changing the xAPI actor identifier
+Change the xAPI actor identifier
 ##################################
 
 The xAPI :ref:`actor <actor_concept>` identifier is a unique user identifier provided

diff --git a/...umentation/how-tos/clickhouse_cluster.rst → ...how-tos/clickhouse/clickhouse_cluster.rst b/...umentation/how-tos/clickhouse_cluster.rst → ...how-tos/clickhouse/clickhouse_cluster.rst
@@ -1,7 +1,7 @@
 .. _clickhouse-cluster:
 
-How To Run Aspects With ClickHouse Cluster
-******************************************
+Run Aspects with a ClickHouse cluster
+*************************************
 
 ClickHouse clusters are an advanced way of running ClickHouse, but offer many benefits for large scale installations. Deciding whether to run in a clustered environment is a big decision with many cost and administrative impacts and should be carefully considered before launching a production environment. In most cases we expect Aspects to perform well without cluster scaling.
 

diff --git a/...cumentation/how-tos/remote_clickhouse.rst → ...ow-tos/clickhouse/clickhouse_external.rst b/...cumentation/how-tos/remote_clickhouse.rst → ...ow-tos/clickhouse/clickhouse_external.rst
@@ -1,7 +1,7 @@
 .. _remote-clickhouse:
 
-Connect to external Clickhouse database
-***************************************
+Connect to an external Clickhouse database
+******************************************
 
 Connect to Clickhouse Cloud
 ###########################

diff --git a/..._documentation/how-tos/clickhouse_sql.rst → ...ion/how-tos/clickhouse/clickhouse_sql.rst b/..._documentation/how-tos/clickhouse_sql.rst → ...ion/how-tos/clickhouse/clickhouse_sql.rst
@@ -1,7 +1,7 @@
 .. _clickhouse-sql:
 
-Clickhouse extra SQL
-********************
+Execute extra Clickhouse SQL
+****************************
 
 You can execute extra Clickhouse SQL at initialization. To do so, you need to use the
 patch `clickhouse-extra-sql`. This patch expects valid Clickhouse SQL code:

diff --git a/docs/technical_documentation/how-tos/clickhouse/index.rst b/docs/technical_documentation/how-tos/clickhouse/index.rst
@@ -0,0 +1,8 @@
+ClickHouse
+##########
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *