Skip to content

Commit 8d05760

Browse files
saraburns1saraburns1
authored
docs: rewriting dbt extension docs (#338)
* docs: update dbt extension & superset extra asset docs with new sample plugin
1 parent bea7a48 commit 8d05760

23 files changed

Lines changed: 305 additions & 303 deletions

‎docs/Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ help:
1414

1515
.PHONY: help Makefile
1616

17+
serve_docs: ## serve the built docs locally to preview the site in the browser
18+
sphinx-autobuild source $(BUILDDIR)/html --ignore '**/_tags/*'
19+
1720
# Catch-all target: route all unknown targets to Sphinx using the new
1821
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
1922
%: Makefile

docs/technical_documentation/how-tos/install_aspects.rst renamed to docs/technical_documentation/how-tos/01_install_aspects.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1-
Aspects Plugin for Tutor
2-
************************
1+
.. _install_aspects:
2+
3+
Install Aspects Plugin for Tutor
4+
********************************
35

46
Aspects is implemented as a Tutor plugin. To learn more about how to install it, please refer to the plugin GitHub site:
57
`<https://github.com/openedx/tutor-contrib-aspects?tab=readme-ov-file#installation>`_

docs/technical_documentation/how-tos/upgrade.rst renamed to docs/technical_documentation/how-tos/02_upgrade.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. _upgrade-aspects:
22

3-
How-to Upgrade Aspects
3+
Upgrade Aspects
44
**********************
55

66
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.

docs/technical_documentation/how-tos/production_configuration.rst renamed to docs/technical_documentation/how-tos/aspects_production_configuration.rst

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. _production_configuration:
22

3-
Configure Aspects for Production
3+
Configure Aspects for production
44
********************************
55

66
Choosing an xAPI Pipeline
@@ -199,13 +199,13 @@ By default, Aspects enables plugin functionality in the LMS that embeds a define
199199
- ``ASPECTS_LEARNER_GROUPS_HELP_MARKDOWN`` controls the content of the "Help" tab in the At-Risk Learners dashboard
200200
- ``ASPECTS_OPERATOR_HELP_MARKDOWN`` controls the content of the "Help" tab in the Operator dashboard
201201

202-
In-context Metrics
202+
In-Context Metrics
203203
------------------
204204

205-
Starting in the Teak Open edX release, Aspects provides in-context metrics in Studio. The following settings controls this functionality.
205+
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.
206206

207-
- ``ASPECTS_ENABLE_STUDIO_IN_CONTEXT_METRICS`` - Enables or disables in-context metrics.
208-
- ``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.
207+
For further customization, the setting ``ASPECTS_IN_CONTEXT_DASHBOARDS`` (in `platform-plugin-aspects`_) is a dictionary mapping block types to in-context dashboards.
208+
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.
209209

210210

211211
Ralph Accessibility
@@ -396,3 +396,4 @@ These are also captured in the Aspects Operator Dashboard as well as a filterabl
396396
.. _Ralph via Helm chart: https://openfun.github.io/ralph/latest/tutorials/helm/
397397
.. _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
398398
.. _transform_tracking_logs: https://event-routing-backends.readthedocs.io/en/latest/technical_documentation/how-tos/how_to_bulk_transform.html
399+
.. _platform-plugin-aspects: https://github.com/openedx/platform-plugin-aspects/blob/main/platform_plugin_aspects/settings/common.py#L112

docs/technical_documentation/how-tos/troubleshooting_aspects.rst renamed to docs/technical_documentation/how-tos/aspects_troubleshooting.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. _troubleshooting_aspects:
22

3-
Troubleshooting Aspects
3+
Troubleshoot Aspects
44
#######################
55

66
Most common problems with Aspects can be fixed by making sure everything is up to date by deleting

‎docs/technical_documentation/how-tos/aspects_without_tutor.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _aspects-without-tutor:
22

3-
Running Aspects Without Tutor
4-
*****************************
3+
Run Aspects without Tutor
4+
*************************
55

66
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.
77

‎docs/technical_documentation/how-tos/backfill.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _backfill:
2+
13
Backfill old or missing data
24
****************************
35

‎docs/technical_documentation/how-tos/changing_actor_identifier.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. _changing_actor_identifier:
22

3-
Changing the xAPI actor identifier
3+
Change the xAPI actor identifier
44
##################################
55

66
The xAPI :ref:`actor <actor_concept>` identifier is a unique user identifier provided

docs/technical_documentation/how-tos/clickhouse_cluster.rst renamed to docs/technical_documentation/how-tos/clickhouse/clickhouse_cluster.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _clickhouse-cluster:
22

3-
How To Run Aspects With ClickHouse Cluster
4-
******************************************
3+
Run Aspects with a ClickHouse cluster
4+
*************************************
55

66
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.
77

docs/technical_documentation/how-tos/remote_clickhouse.rst renamed to docs/technical_documentation/how-tos/clickhouse/clickhouse_external.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _remote-clickhouse:
22

3-
Connect to external Clickhouse database
4-
***************************************
3+
Connect to an external Clickhouse database
4+
******************************************
55

66
Connect to Clickhouse Cloud
77
###########################

0 commit comments

Comments
 (0)