diff --git a/lms/djangoapps/edxnotes/README.rst b/lms/djangoapps/edxnotes/README.rst index 8ba97c1877..1f1820346d 100644 --- a/lms/djangoapps/edxnotes/README.rst +++ b/lms/djangoapps/edxnotes/README.rst @@ -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 `_ 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 ======== diff --git a/lms/envs/docs/README.rst b/lms/envs/docs/README.rst index b38c2d2886..34211a5751 100644 --- a/lms/envs/docs/README.rst +++ b/lms/envs/docs/README.rst @@ -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): """ diff --git a/openedx/core/djangoapps/course_apps/docs/decisions/001-course-apps.rst b/openedx/core/djangoapps/course_apps/docs/decisions/001-course-apps.rst index 1ee8555c68..4491779a27 100644 --- a/openedx/core/djangoapps/course_apps/docs/decisions/001-course-apps.rst +++ b/openedx/core/djangoapps/course_apps/docs/decisions/001-course-apps.rst @@ -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 diff --git a/xmodule/modulestore/docs/index.rst b/xmodule/modulestore/docs/index.rst index a16c92d84b..6a6db46336 100644 --- a/xmodule/modulestore/docs/index.rst +++ b/xmodule/modulestore/docs/index.rst @@ -1,8 +1,8 @@ .. _edX Modulestores: -########################### +################ edX Modulestores -########################### +################ .. toctree:: :maxdepth: 2 diff --git a/xmodule/modulestore/docs/mixedmodulestore.rst b/xmodule/modulestore/docs/mixedmodulestore.rst index 3a8d84c9f8..3ec11c22f5 100644 --- a/xmodule/modulestore/docs/mixedmodulestore.rst +++ b/xmodule/modulestore/docs/mixedmodulestore.rst @@ -1,6 +1,6 @@ -################# +################ MixedModuleStore -################# +################ MixedModuleStore provides a common API for all modulestore functions. diff --git a/xmodule/modulestore/docs/overview.rst b/xmodule/modulestore/docs/overview.rst index 5ffa719d62..a5b56689e4 100644 --- a/xmodule/modulestore/docs/overview.rst +++ b/xmodule/modulestore/docs/overview.rst @@ -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. \ No newline at end of file diff --git a/xmodule/modulestore/docs/split-mongo.rst b/xmodule/modulestore/docs/split-mongo.rst index 4df1b7ccce..19f116aeb2 100644 --- a/xmodule/modulestore/docs/split-mongo.rst +++ b/xmodule/modulestore/docs/split-mongo.rst @@ -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 `, Split Mongo enables content reuse. A single `XBlock