Andal.LND/edx-platform
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: cleanup

Browse Source 
- rst heading definitions
- indirect hyperlinks and code-blocks for better readability
This commit is contained in:
Emad Rad
2024-05-25 18:08:25 +03:30
parent c27d55a253
commit 4529041643
7 changed files with 94 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
lms/djangoapps/edxnotes/README.rst
View File

@@ -2,15 +2,24 @@ Status: Maintenance
Responsibilities
================
The edxnotes app is responsible for displaying parts of the Notes UI to students in different parts of the LMS, as well as figuring out whether Notes is enabled for a particular situation. The bulk of the actual work in storing the notes is done by a separate service (see the edx-notes-api repo).
The edxnotes app is responsible for displaying parts of the Notes UI to students in different parts of the LMS, as well as figuring out whether Notes is enabled for a particular situation. The bulk of the actual work in storing the notes is done by a separate service (see the `edx-notes-api`_ repo).
.. _edx-notes-api: https://github.com/openedx/edx-notes-api/
Direction: Extract into Plugin
==============================
Notes needs to insert a new tab into the LMS courseware, as well as wrap/decorate the courseware XBlock output so that it can add annotation capability to it. Both of these can now be done via plugins (decorating XBlock output can be done with XBlock Asides), and this app should be extracted into a separate repository.
This app is also currently proxying some requests through the LMS instead of hitting its service endpoint directly. It should instead always let the user's browser hit the edx-notes-api service directly.
Notes needs to insert a new tab into the LMS courseware, as well as wrap/decorate the courseware XBlock output so that it can add annotation capability to it.
Both of these can now be done via plugins (decorating XBlock output can be done with XBlock Asides), and this app should be extracted into a separate repository.
The edxnotes app also has an endpoint to get JWT tokens that the edx-notes-api will accept. This should be removed, and the edx-notes-api service converted to use the OAuth2 + JWT Cookie approach detailed in the `Transport JWT in HTTP Cookies <https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/oauth_dispatch/docs/decisions/0009-jwt-in-session-cookie.rst>`_ decision record for ``oauth_dispatch``.
This app is also currently proxying some requests through the LMS instead of hitting its service endpoint directly.
It should instead always let the user's browser hit the edx-notes-api service directly.
The edxnotes app also has an endpoint to get JWT tokens that the edx-notes-api will accept.
This should be removed, and the edx-notes-api service converted to use the OAuth2 + JWT Cookie approach detailed in the `Transport JWT in HTTP Cookies`_ decision record for ``oauth_dispatch``.
.. _Transport JWT in HTTP Cookies: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/oauth_dispatch/docs/decisions/0009-jwt-in-session-cookie.rst
Glossary
========

26
lms/envs/docs/README.rst
View File

@@ -1,7 +1,7 @@
LMS Configuration Settings
==========================
##########################
The lms.envs module contains project-wide settings, defined in python modules
The ``lms.envs`` module contains project-wide settings, defined in python modules
using the standard `Django Settings`_ mechanism, plus some Open edX
particularities, which we describe below.
@@ -9,9 +9,12 @@ particularities, which we describe below.
YAML Configuration Files
------------------------
************************
In addition, there is a mechanism for reading and overriding configuration settings from YAML files on-disk. The :file:`/lms/envs/production.py` module loads settings from a YAML file. The location of the YAML file is pulled from the value of the ``LMS_CFG`` environment variable. Except for a limited set of exceptions, if a key exists in the YAML file, it will be injected into the settings module as it is defined in the YAML file.
In addition, there is a mechanism for reading and overriding configuration settings from YAML files on-disk.
The :file:`/lms/envs/production.py` module loads settings from a YAML file.
The location of the YAML file is pulled from the value of the ``LMS_CFG`` environment variable.
Except for a limited set of exceptions, if a key exists in the YAML file, it will be injected into the settings module as it is defined in the YAML file.
The YAML file allow Open edX operators to configure the Django runtime
without needing to make any changes to source-controlled python files in
@@ -23,7 +26,7 @@ repo`_ and available in the ``/edx/etc/`` folder on edX servers.
Feature Flags and Settings Guidelines
-------------------------------------
*************************************
For guidelines on using Django settings and feature flag mechanisms in the edX
platform, please see `Feature Flags and Settings`_.
@@ -32,16 +35,19 @@ platform, please see `Feature Flags and Settings`_.
Derived Settings
----------------
****************
In cases where you need to define one or more settings relative to the value of
another setting, you can explicitly designate them as derived calculations.
This can let you override one setting (such as a path or a feature toggle) and
have it automatically propagate to other settings which are defined in terms of
that value, without needing to track down all potentially impacted settings and
explicitly override them as well. This can be useful for test setting overrides
explicitly override them as well. This can be useful for test setting overrides
even if you don't anticipate end users customizing the value very often.
For example::
For example:
.. code-block:: python
def _make_locale_paths(settings):
locale_paths = [settings.REPO_ROOT + '/conf/locale'] # edx-platform/conf/locale/
@@ -61,7 +67,9 @@ defined in ``lms/envs/common.py`` and you're using ``lms/envs/production.py`` wh
includes overrides both from that module and the JSON configuration files.
List entries and dictionary values can also be derived from other settings, even
when nested within each other::
when nested within each other:
.. code-block:: python
def _make_mako_template_dirs(settings):
"""

50
openedx/core/djangoapps/course_apps/docs/decisions/001-course-apps.rst
View File

@@ -1,12 +1,13 @@
Course Apps API
_______________
###############
Status
======
******
Proposal
Context
=======
*******
The new `Course Authoring MFE`_ includes a new UX called "Pages and Resources"
for configuring different aspects of the course experience such as progress,
@@ -27,7 +28,7 @@ enable/disable these apps using the API.
Decision
========
########
We propose to call such individual course features "Course Apps". They can be
introduced as a new type of Open edX plugin. Any functionality that can be
@@ -39,16 +40,29 @@ some bits of metadata, such as a name, a description etc. Additionally we will
need a common interface for such apps so they can be enabled/disabled using
a standard common interface.
To do this we can follow the example of existing plugins, [such as Course
Tabs](https://github.com/openedx/edx-platform/blob/636b2ca4c5add531cfce755fdb8965599acd79e0/common/lib/xmodule/xmodule/tabs.py#L24-L243),
To do this we can follow the example of existing plugins, `such as Course Tabs`_,
which provide a specific Python class that the plugin can inherit from, or
implement. The required metadata and features, can be implemented as class
attributes, and methods on this class.
We can then discover the installed apps using the existing tooling for plugins
using a subclass of PluginManager designed for this purpose. Here is an example
for [Course
Tabs](https://github.com/openedx/edx-platform/blob/636b2ca4c5add531cfce755fdb8965599acd79e0/openedx/core/lib/course_tabs.py#L13-L47)
using a subclass of ``PluginManager`` designed for this purpose.
Here is an example for `CourseTabs`_:
.. code-block:: python
class CourseTabPluginManager(PluginManager):
"""
Manager for all of the course tabs that have been made available.
All course tabs should implement `CourseTab`.
"""
NAMESPACE = COURSE_TAB_NAMESPACE
@classmethod
def get_tab_types(cls):
"""
Returns the list of available course tabs in their canonical order.
It might not always make sense for an app installed in this way to be
automatically show up for use on all courses. So each app will expose a method
@@ -85,14 +99,17 @@ In the case of Course Apps, the standard plugin API will automatically discover
all installed apps. Inactive apps will be filtered out during the availability
check.
Course App Plugin Class
-----------------------
.. _such as Course Tabs: https://github.com/openedx/edx-platform/blob/636b2ca4c5add531cfce755fdb8965599acd79e0/common/lib/xmodule/xmodule/tabs.py#L24-L243
.. _CourseTabs: https://github.com/openedx/edx-platform/blob/636b2ca4c5add531cfce755fdb8965599acd79e0/openedx/core/lib/course_tabs.py#L13-L47
To be loaded as a Course App, you need to provide an entrypoint in `setup.py`
with the namespace "openedx.course_app". The entry should point to a Python
Course App Plugin Class
=======================
To be loaded as a Course App, you need to provide an entrypoint in ``setup.py``
with the namespace ``openedx.course_app``. The entry should point to a Python
class with the following basic structure:
.. code-block :: python
.. code-block:: python
class CourseApp:
# The app id should match what is specified in the setup.py entrypoint
@@ -143,7 +160,7 @@ such a class and have these class methods call back to the existing code for
availability checks and enabled checks.
Course Apps API
---------------
===============
Each app has some associated metadata:
@@ -218,9 +235,8 @@ link should only be provided for Course Apps that don't have a UI in the course
authoring MFE yet. If a partial UI exists, the MFE settings view can always link
back to the old studio view from there.
Consequences
============
************
- A new Course Apps API that consistently uses a standard mechanism (a plugin
class) for discovering Course Apps, determining their availability and

4
xmodule/modulestore/docs/index.rst
View File

@@ -1,8 +1,8 @@
.. _edX Modulestores:
###########################
################
edX Modulestores
###########################
################
.. toctree::
:maxdepth: 2

4
xmodule/modulestore/docs/mixedmodulestore.rst
View File

@@ -1,6 +1,6 @@
#################
################
MixedModuleStore
#################
################
MixedModuleStore provides a common API for all modulestore functions.

16
xmodule/modulestore/docs/overview.rst
View File

@@ -1,6 +1,6 @@
#################################
################################
Overview of the edX Modulestores
#################################
################################
The edX Platform uses several different modulestores to store course data. Each
of these modulestores is in use on edx.org.
@@ -11,9 +11,9 @@ See:
* `DraftModuleStore`_
* :ref:`Split Mongo Modulestore`
***************
**************
XMLModuleStore
***************
**************
The XMLModuleStore was the first modulestore used for the edX Platform.
@@ -23,9 +23,9 @@ server starts, XMLModuleStore loads every block for every course into memory.
XMLModuleStore is read-only and does not enable users to change a course
without restarting the server.
*****************
****************
DraftModuleStore
*****************
****************
DraftModuleStore was the next generation modulestore and provides greater
scalability by allowing random access to course blocks and loading blocks on
@@ -35,9 +35,9 @@ DraftModuleStore allows editing of courses without restarting the server.
In addition, DraftModuleStore stores a draft version of some types of blocks.
*****************
***********
Split Mongo
*****************
***********
Split Mongo is the newest modulestore. See the :ref:`Split Mongo Modulestore`
chapter for more information.

38
xmodule/modulestore/docs/split-mongo.rst
View File

@@ -1,8 +1,8 @@
.. _Split Mongo Modulestore:
############################
#######################
Split Mongo Modulestore
############################
#######################
See:
@@ -11,9 +11,9 @@ See:
* `Split Mongo Capabilities`_
************************
********
Overview
************************
********
*Split Mongo* is the term used for the new edX modulestore. Split Mongo is
built on mongoDB. For information about mongoDB, see the `mongoDB website`_.
@@ -30,9 +30,9 @@ use more advanced capabilities when developing and managing courses.
.. _mongoDB website: http://www.mongodb.org
************************
**********************
Split Mongo Data Model
************************
**********************
In the Split Mongo data model, edX courses are split into three collections:
@@ -42,9 +42,9 @@ In the Split Mongo data model, edX courses are split into three collections:
.. Structures link is a workaround; "Course Structures" as label is already taken
=============
============
Course Index
=============
============
The course index is a dictionary that stores course IDs. Each course ID points
to a course structure.
@@ -69,13 +69,13 @@ In the edX Platform:
about page, course updates, other course pages, sections or subsections,
the draft branch is automatically published; that is, it becomes the
published branch.
* For units and components, changes are saved in the draft branch. The user
must publish the unit to change the draft branch to the published branch.
When the user begins another set of changes, the draft branch is updated.
Course Reruns
**************
*************
The edX Platform enables you to rerun a course. When you rerun a course, a new
course index is created. The new course index points to the same course
@@ -83,9 +83,9 @@ structure as the original course index.
.. _Structures:
==========================
=================
Course Structures
==========================
=================
The course structure defines, or outlines, the content of a course.
@@ -104,9 +104,9 @@ when a course author changes a course, or a block in the course, a new course
structure is saved; the previous course structure, and previous versions of
blocks within the structure, remain in the database and are not modified.
==========================
==================
XBlock Definitions
==========================
==================
XBlock definitions contain the content of each block. For some blocks, such as
sections and subsections, the definition consists of the block's display name.
@@ -129,7 +129,7 @@ enable:
* `Multiple Course Branches`_
* `Versioning`_
* `Content Reuse`_
While these capabilities are not fully implemented in the edX Platform, Split
Mongo is designed to allow future enhancements that enable these content
management capabilities.
@@ -145,9 +145,9 @@ different structure.
The edX Platform currently uses a draft and a published branch for a course.
Future enhancements may use other branches.
============
==========
Versioning
============
==========
In Split Mongo, every change to a course or a block within the course is saved,
with the time and user recorded.
@@ -155,9 +155,9 @@ with the time and user recorded.
Versioning enables future enhancements such as allowing course authors to
revert a course or block to a previous version.
==============
=============
Content Reuse
==============
=============
By using pointers to reference XBlock definitions from :ref:`course structures
<Structures>`, Split Mongo enables content reuse. A single `XBlock