From b842d4b1f119b76bda12f992bd931bafe7b88441 Mon Sep 17 00:00:00 2001 From: Nimisha Asthagiri Date: Tue, 4 Dec 2018 18:40:08 -0500 Subject: [PATCH] Colocate Modulestore docs with modulestore code --- .../xmodule/modulestore/docs/index.rst | 12 ++ .../modulestore/docs/mixedmodulestore.rst | 12 ++ .../xmodule/modulestore/docs/overview.rst | 43 +++++ .../xmodule/modulestore/docs/split-mongo.rst | 168 ++++++++++++++++++ 4 files changed, 235 insertions(+) create mode 100644 common/lib/xmodule/xmodule/modulestore/docs/index.rst create mode 100644 common/lib/xmodule/xmodule/modulestore/docs/mixedmodulestore.rst create mode 100644 common/lib/xmodule/xmodule/modulestore/docs/overview.rst create mode 100644 common/lib/xmodule/xmodule/modulestore/docs/split-mongo.rst diff --git a/common/lib/xmodule/xmodule/modulestore/docs/index.rst b/common/lib/xmodule/xmodule/modulestore/docs/index.rst new file mode 100644 index 0000000000..a16c92d84b --- /dev/null +++ b/common/lib/xmodule/xmodule/modulestore/docs/index.rst @@ -0,0 +1,12 @@ +.. _edX Modulestores: + +########################### +edX Modulestores +########################### + +.. toctree:: + :maxdepth: 2 + + overview + mixedmodulestore + split-mongo \ No newline at end of file diff --git a/common/lib/xmodule/xmodule/modulestore/docs/mixedmodulestore.rst b/common/lib/xmodule/xmodule/modulestore/docs/mixedmodulestore.rst new file mode 100644 index 0000000000..3a8d84c9f8 --- /dev/null +++ b/common/lib/xmodule/xmodule/modulestore/docs/mixedmodulestore.rst @@ -0,0 +1,12 @@ +################# +MixedModuleStore +################# + +MixedModuleStore provides a common API for all modulestore functions. + +In addition, MixedModuleStore allows you to select which modulestore a +specific course is stored in (XMLModuleStore, DraftModuleStore, Split Mongo) +and routes requests for that course to the correct modulestore. + +MixedModuleStore can also handle some conversions from one modulestore to +another. \ No newline at end of file diff --git a/common/lib/xmodule/xmodule/modulestore/docs/overview.rst b/common/lib/xmodule/xmodule/modulestore/docs/overview.rst new file mode 100644 index 0000000000..5ffa719d62 --- /dev/null +++ b/common/lib/xmodule/xmodule/modulestore/docs/overview.rst @@ -0,0 +1,43 @@ +################################# +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. + +See: + +* `XMLModuleStore`_ +* `DraftModuleStore`_ +* :ref:`Split Mongo Modulestore` + +*************** +XMLModuleStore +*************** + +The XMLModuleStore was the first modulestore used for the edX Platform. + +XMLModuleStore uses a file system that stores XML-based courses. When the LMS +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 +requests. + +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/common/lib/xmodule/xmodule/modulestore/docs/split-mongo.rst b/common/lib/xmodule/xmodule/modulestore/docs/split-mongo.rst new file mode 100644 index 0000000000..4df1b7ccce --- /dev/null +++ b/common/lib/xmodule/xmodule/modulestore/docs/split-mongo.rst @@ -0,0 +1,168 @@ +.. _Split Mongo Modulestore: + +############################ +Split Mongo Modulestore +############################ + +See: + +* `Overview`_ +* `Split Mongo Data Model`_ +* `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`_. + +The "split" in Split Mongo refers to how a course is split into three types of +information: + +* The course identity, referred to as the course index +* The course structure +* The course content, referred to as XBlock definitions. + +This separation of identity, structure, and content enables course authors to +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: + +* `Course Index`_ +* :ref:`Structures` +* `XBlock Definitions`_ + +.. 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. + +The course index supports multiple branches of a course. The index can store +multiple entries for a course ID, with each entry pointing to a different +course structure that corresponds to a different branch. + +As currently implemented, for each course, there is a branch for both the +published and draft versions of the course. The published and draft branches of +the course point to different structures. + +In the edX Platform: + +* Students using the LMS see and interact with the published version of the + course. + +* Course team members using edX Studio make changes to the draft version of + the course. + + * When the user changes the course outline, display names, the course + 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 +structure as the original course index. + +.. _Structures: + +========================== +Course Structures +========================== + +The course structure defines, or outlines, the content of a course. + +A course structure is made up of blocks in a tree data structure. Blocks are +objects in a course, such as the course itself, sections, subsections, and +units. A block can reference other blocks; for example, a section references +one or more subsections. Each block has a unique ID that is generated by the +edX Platform. + +Each block in the course structure points to an XBlock definition. Different +blocks, in the same or in different structures, can point to the same +definition. + +Course structures, and each block within a structure, are versioned. That is, +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. +For components, such as HTML or problem components, the definition also +contains the content of the object. A definition can be referenced by multiple +blocks. + +XBlock definitions are versioned. That is, when a course author changes +content, a new XBlock definition for that object is saved; the previous +definition remains in the database and is not modified. + +************************ +Split Mongo Capabilities +************************ + +The Split Mongo data model enables the edX Platform to implement advanced +content management functionality. Specifically, Split Mongo is designed to +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. + +======================== +Multiple Course Branches +======================== + +Split Mongo enables multiple branches of a course. The `course index _ can have multiple entries for a course ID, each of which points to a +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. + +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 +definition `_ can be referenced from multiple course +structures. + +Future enhancements to the edX Platform can allow course authors to reuse an +XBlock in multiple contexts, streamlining course development and maintenance. \ No newline at end of file