Merge pull request #95 from openedx/bmtcril/beta_doc_updates

Doc updates
openedx · Sep 11, 2023 · 21c3ef1 · 21c3ef1
2 parents c33a32b + 2059c28
commit 21c3ef1
Show file tree

Hide file tree

Showing 17 changed files with 144 additions and 37 deletions.
diff --git a/Makefile b/Makefile
@@ -33,9 +33,13 @@ requirements:
 	pip-sync requirements/base.txt
 
 serve_docs:
-	sphinx-autobuild docs/ docs/_build/html/
+	sphinx-autobuild -W docs/ docs/_build/html/
+
+# Emulate the build step on RTD to flush out errors ahead pushing
+check_docs:
+	sphinx-build -T -E -W --keep-going docs/ docs/_build/html
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/AspectsDataFlows.pdf b/docs/_static/AspectsDataFlows.pdf
diff --git a/docs/concepts/aspects_overview.rst b/docs/concepts/aspects_overview.rst
@@ -0,0 +1,47 @@
+.. _aspects-overview:
+
+Aspects Overview
+****************
+
+What it is
+##########
+
+Aspects captures learning events and transforms them into data visualizations. When a learner enrolls in a course, that event is captured in a database and displayed back to the course instructor as a graph of learner enrollments over time. When an instructor adds a new problem to their course and publishes it, the course data is refreshed in the database so that it can immediately begin showing information about how learners answer the question.
+
+Aspects is being built to help Open edX users answer questions like:
+
+- How many learners were active in a specified time period?
+- How many learners are participating in forum discussions?
+- How often was this problem answered correctly vs incorrectly?
+- How much of each video is watched, and which sections were re-watched most?
+
+By default Aspects focuses on learner privacy and does not include the ability to identify learners in the reports. This type of functionality can be added via plugins if desirable, but can have negative performance and user interface issues for large courses.
+
+How it works
+############
+
+Many actions in the Open edX platform generate :ref:`tracking-logs`, which are captured by the event-routing-backends plugin, transformed into :ref:`xAPI <xapi-concepts>` statements, and either forwarded to the :ref:`Ralph <ralph>` learning record store or sent to the :ref:`Vector <vector>` log statement forwarder (depending on configuration). Either option will save the xAPI statement to a :ref:`ClickHouse <clickhouse>` analytic database. Once in the database, the statement can be transformed and aggregated in many different ways using different types of views or intermediate tables to generate data that is then displayed using :ref:`Superset <superset>`.
+
+See the :download:`Data Flow PDF </_static/AspectsDataFlows.pdf>` for more details.
+
+For Instructors
+~~~~~~~~~~~~~~~
+
+By default instructors can use their Open edX installation to single sign-on to the Superset instance. Superset will pull in the courses that you are an instructor on from the LMS and assign you appropriate permissions. It will also pull in your preferred language from the LMS and attempt to display content in that language. Once logged in you will be able to see the Instructor Dashboard. From here you can navigate to different tabs and view the different :ref:`Instructor Reports <instructor-reports>` made available by your site operators.
+
+For Analysts
+~~~~~~~~~~~~
+
+Data Analysts don't yet have specific roles that we can pull from the Open edX installation, but we hope to be able to do that soon. For now, you should be able to get appropriate permissions assigned to you by a site operator or administrator with the necessary permissions. In addition to being able to see the Instructor Reports you may get access to the Operator Reports and the ability to use the SQL Lab to run queries directly against the different ClickHouse data sources.
+
+See the `Superset <https://superset.apache.org/docs/intro>`_. documentation for more information on how to use the advanced Superset features.
+
+For Operators
+~~~~~~~~~~~~~
+
+Site operators have full administrative access to Superset as well as a dashboard :ref:`Operator Reports <operator-reports>` of metrics to monitor instance-wide health and activity. See the `Superset <https://superset.apache.org/docs/intro>`_. documentation for more information on how to use the advanced Superset features. You can also create new dashboards and charts.
+
+For Developers
+~~~~~~~~~~~~~~
+
+Developers can :ref:`extend <extensions>` Aspects in numerous ways to work with the many ways Open edX can be configured and unique reporting needs for each organization.
diff --git a/docs/concepts/clickhouse.rst b/docs/concepts/clickhouse.rst
@@ -1,8 +1,10 @@
+.. _clickhouse:
+
 Clickhouse
 ****************************
 
-ClickHouse is a high-performance, column-oriented SQL database management system (DBMS) 
-for online analytical processing (OLAP). It is used as the backend storage for the Aspects 
+ClickHouse is a high-performance, column-oriented SQL database management system (DBMS)
+for online analytical processing (OLAP). It is used as the backend storage for the Aspects
 project that powers Superset.
 
 Aspects is compatible with Clickhouse Cloud and on premise Clickhouse instances.
@@ -34,5 +36,5 @@ From here, the main table is split into different tables and views for performan
 
 - Materialized views transform the xAPI statements into tables that are structured for performance.
 
-- Views are created on top of these tables to generate specific reports such as "Video Views" 
+- Views are created on top of these tables to generate specific reports such as "Video Views"
   and "Enrollments by Day".
diff --git a/docs/concepts/index.rst b/docs/concepts/index.rst
@@ -5,6 +5,7 @@ Concepts
    :glob:
    :maxdepth: 2
 
+   Aspects Overview <aspects_overview>
    xAPI <xapi_concepts>
    Tracking Logs <tracking_logs>
    Clickhouse <clickhouse>

diff --git a/docs/concepts/ralph.rst b/docs/concepts/ralph.rst
@@ -1,3 +1,5 @@
+.. _ralph:
+
 Ralph
 *****
 
@@ -12,7 +14,7 @@ Although Ralph has usages such as:
 - Validate xAPI statements.
 - Store events to different `backends <https://openfun.github.io/ralph/backends/>`_.
 
-In the aspects project, Ralph is optionally used as the API server that connects Open edX 
+In the aspects project, Ralph is optionally used as the API server that connects Open edX
 and Clickhouse database. Ralph receives the xAPI statements from Open edX and stores them
 in the Clickhouse database after validating the data.
 

diff --git a/docs/concepts/superset.rst b/docs/concepts/superset.rst
@@ -1,3 +1,5 @@
+.. _superset:
+
 Superset
 ********
 

diff --git a/docs/concepts/tracking_logs.rst b/docs/concepts/tracking_logs.rst
@@ -1,16 +1,18 @@
+.. _tracking-logs:
+
 Tracking Logs
 *************
 
-The event-tracking library tracks context-aware semi-structured system events. It captures 
+The event-tracking library tracks context-aware semi-structured system events. It captures
 and stores events with nested data structures in order to truly take advantage of schemaless
 data storage systems.
 
-This library produces trackings logs which can be stored in multiple destinations. 
+This library produces trackings logs which can be stored in multiple destinations.
 
 In Aspects those trackings logs are captured by Vector and stored in the Clickhouse database.
 Those are not really used by the Aspects plugin, but they are there for custom reporting
 capabilities.
 
 Note that we use xAPI statements over tracking logs, because those store a lot of
-PII data, such as usernames, email addresses, browser data, and IP addresses; 
+PII data, such as usernames, email addresses, browser data, and IP addresses;
 while xAPI statements are more generic.
diff --git a/docs/concepts/vector.rst b/docs/concepts/vector.rst
@@ -1,3 +1,5 @@
+.. _vector:
+
 Vector
 ******
 
@@ -27,7 +29,7 @@ Vector can be deployed in two roles:
   from Vector agents and sends it to a destination.
 
 
-We use the role `Agent` to collect tracking logs and xAPI events from the lms and send it to 
+We use the role `Agent` to collect tracking logs and xAPI events from the lms and send it to
 the Clickhouse sink.
 
 For instance, Aspects has Sources configured for xAPI logging statements (optionally

diff --git a/docs/concepts/xapi_concepts.rst b/docs/concepts/xapi_concepts.rst
@@ -1,11 +1,13 @@
+.. _xapi-concepts:
+
 xAPI Concepts
 *************
 
 Introduction
 ###################
 
-xAPI, also known as the Experience API or Tin Can API, is a specification for capturing 
-and tracking learning experiences in a wide range of contexts. It is an e-learning 
+xAPI, also known as the Experience API or Tin Can API, is a specification for capturing
+and tracking learning experiences in a wide range of contexts. It is an e-learning
 standard that allows organizations to gather data about learner activities and interactions
 across various platforms and devices. xAPI provides a flexible and comprehensive
 framework for collecting, storing, and analyzing learning data, enabling a deeper
@@ -21,7 +23,7 @@ The xAPI specification consists of three key components:
 Actor
 ~~~~~
 In xAPI, an actor represents an entity that interacts with the learning system.
-It can be a learner, instructor, system administrator, or any other agent 
+It can be a learner, instructor, system administrator, or any other agent
 involved in the learning process. Actors are identified using a unique identifier,
 such as an email address or username.
 
@@ -37,8 +39,8 @@ Learning Record Store (LRS)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The Learning Record Store serves as the repository for storing and retrieving xAPI
 statements. It is a database or storage system that receives and securely stores
-the statements generated by learning activities. The LRS enables the collection 
-and organization of learning data from various sources, allowing for robust 
+the statements generated by learning activities. The LRS enables the collection
+and organization of learning data from various sources, allowing for robust
 analysis and reporting of learner experiences.
 
 Together, these components form the foundation of the xAPI ecosystem, enabling

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,16 +1,18 @@
-.. Open edX Aspects documentation master file, created by
-   sphinx-quickstart on Thu Jan  5 14:35:06 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to the Open edX Aspects documentation!
 ==============================================
 
-* Note: we are in the progress of changing the project name and documentation is still being updated from OARS to Aspects!
+Aspects is an analytics system for Open edX, bringing actionable data about course and learner performance to instructors and site operators. It is primarily a Tutor plugin that ties together data from the Open edX learning management system and Studio using open source tools to aggregate and transform learning traces into data visualizations.
+
+As of September 2023 it is in beta and seeking testers, which you can learn about at the `beta wiki page
+<https://openedx.atlassian.net/wiki/spaces/COMM/pages/3861512203/Aspects+Beta>`_.
+
+Installation instructions are available on the plugin site: https://github.com/openedx/tutor-contrib-aspects
+
+You can get started reading about the project in the :ref:`aspects-overview`, or look through the various pages below for more details!
+
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
    Concepts <concepts/index>
    Decisions <decisions/index>

diff --git a/docs/quickstarts/index.rst b/docs/quickstarts/index.rst
@@ -1,6 +1,9 @@
 Quick Starts
 ############
 
+Installation instructions are available on the plugin site: https://github.com/openedx/tutor-contrib-aspects
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Content:

diff --git a/docs/quickstarts/ralph.rst b/docs/quickstarts/ralph.rst
@@ -3,27 +3,41 @@
 Ralph
 ******
 
-Ralph is the default option to send xAPI events to Clickhouse. To run it
-make sure to enable the `RUN_RALPH` option in the `config.yml` file.
+Installation instructions for Aspects are available on the plugin site: https://github.com/openedx/tutor-contrib-aspects
+
+Ralph is the default option to send xAPI events to Clickhouse. To run it make sure to enable the `RUN_RALPH` option in the `config.yml` file.
 
 .. code-block:: yaml
 
     RUN_RALPH: True
 
+    # We recommend only running Ralph or Vector for performance reasons, so
+    # suggest turning off Vector here
+    RUN_VECTOR: False
+
+
 Aspects provides the following configuration options:
 
 .. code-block:: yaml
-    
-    # If True, the public URL ralph.{{LMS_HOST}} will be used instead of the internal one
-    # Useful is you want Ralph to be used by external services
+
+    # If True, the public URL ralph.{{LMS_HOST}} will be made publicly
+    # available, otherwise Ralph will only be available on local Docker network.
     RALPH_ENABLE_PUBLIC_URL: False
     RALPH_PORT: 8100
+
+    # If you are running Sentry for service monitoring, you can configure it
+    # here to expose Ralph information.
     RALPH_SENTRY_DSN: ""
     RALPH_EXECUTION_ENVIRONMENT: "production"
     RALPH_SENTRY_CLI_TRACES_SAMPLE_RATE: 1.0
     RALPH_SENTRY_LRS_TRACES_SAMPLE_RATE: 0.1
     RALPH_SENTRY_IGNORE_HEALTH_CHECKS: True
-    RALPH_EXTRA_SETTINGS: {} # Any extra setting for Ralph such backends or cache settings
+
+    # Any extra setting for Ralph such backends or cache settings can be added
+    # here
+    RALPH_EXTRA_SETTINGS: {}
+
+    # These will be generated by Tutor automatically, but can be overridden
     RALPH_ADMIN_USERNAME: "admin"
     RALPH_ADMIN_PASSWORD: "secure-password"
     RALPH_LMS_USERNAME: "lms"
@@ -34,5 +48,11 @@ To connect an external Ralph instance, you can use the following configuration:
 
 .. code-block:: yaml
 
+    # Turns off running Ralph in the Tutor environment
+    RUN_RALPH: False
+
+    # The hostname of your existing Ralph installation
     RALPH_HOST: "ralph.example.com"
-    RALPH_RUN_HTTPS: False # If True, Ralph will use HTTPS instead of HTTP
+
+    # If True, Aspects will connect to Ralph via HTTPS instead of HTTP
+    RALPH_RUN_HTTPS: False
diff --git a/docs/quickstarts/vector.rst b/docs/quickstarts/vector.rst
@@ -3,27 +3,27 @@
 Vector
 ******
 
-Vector is an alternative option to send xAPI events to Clickhouse. It can be
-run along with Ralph, but to optimize resources we encourage you to only use one.
+Installation instructions for Aspects are available on the plugin site: https://github.com/openedx/tutor-contrib-aspects
 
-To configure Vector as the xAPI event handler, you can use the following
-configuration:
+Vector is an alternative option to send xAPI events to Clickhouse. It can be run along with Ralph, but to optimize resources we encourage you to only use one.
+
+To configure Vector as the xAPI event handler, you can use the following configuration:
 
 .. code-block:: yaml
 
     # Disable ralph
     RUN_RALPH: False
     # Enable vector
     RUN_VECTOR: True
-    # Change the xAPI database
-    ASPECTS_XAPI_DATABASE: "openedx" # default is "xapi"
+    # Change the xAPI database to the one Vector uses
+    ASPECTS_XAPI_DATABASE: "openedx"
 
 
 Aspects provides the following configuration options:
 
 .. code-block:: yaml
-    
+
     ASPECTS_CLICKHOUSE_VECTOR_USER: "vector"
     ASPECTS_CLICKHOUSE_VECTOR_PASSWORD: "secure-password"
     # The default name is used to keep backwards compatibility with Cairn
-    ASPECTS_VECTOR_RAW_TRACKING_LOGS_TABLE: "_tracking"
+    ASPECTS_VECTOR_RAW_TRACKING_LOGS_TABLE: "_tracking"
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -1,2 +1,8 @@
 Reference Material
 ##################
+
+.. toctree::
+   :maxdepth: 2
+
+   Instructor Reports <instructor_reports>
+   Operator Reports <operator_reports>
diff --git a/docs/reference/instructor_reports.rst b/docs/reference/instructor_reports.rst
@@ -0,0 +1,6 @@
+.. _instructor-reports:
+
+Instructor Reports
+##################
+
+Coming soon
diff --git a/docs/reference/operator_reports.rst b/docs/reference/operator_reports.rst
@@ -0,0 +1,6 @@
+.. _operator-reports:
+
+Operator Reports
+################
+
+Coming soon