[BD-34] PR for dev documentation related to extending the Open edX platform #37
Conversation
|
Thanks for the pull request, @PrecisionWordcraft! I've created BLENDED-751 to keep track of it in Jira. When this pull request is ready, tag your edX technical lead. |
| You can also render an individual XBlock in HTML; see `Rendering XBlocks with the XBlock URL`_ . | ||
|
|
There was a problem hiding this comment.
This content currently lives in edx-documentation/en-us/shared/dev. I didn't see any reason not to move it into this file. There are no links to it within edx-documentation.
docs/extending/xblocks.rst
Outdated
| described in the `Open edX XBlock Tutorial <https://edx.readthedocs.io/projects/xblock-tutorial/en/latest/>`_, look in the | ||
| ``setup.py`` file that was created.) |
There was a problem hiding this comment.
This link now needs to be external.
There was a problem hiding this comment.
If we set up an intersphinx mapping (like this: https://github.com/edx/edx-documentation/blob/1c1c551e350bb9e5e8280474d3af4a81a02a3deb/shared/conf.py#L172-L189), then Sphinx can manage these links internally.
There was a problem hiding this comment.
If we set up an intersphinx mapping (like this: https://github.com/edx/edx-documentation/blob/1c1c551e350bb9e5e8280474d3af4a81a02a3deb/shared/conf.py#L172-L189), then Sphinx can manage these links internally.
See commit cd5903d
| other course content component, or for sequential or vertical course container | ||
| component. There are several ways to find the ``usage_id`` for an XBlock in the | ||
| LMS, including viewing either the staff debug info or the page source. For more | ||
| information, see `Finding the Usage ID for Course Content <https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/latest/course_features/lti/lti_address_content.html#finding-the-usage-id-for-course-content>`_. |
There was a problem hiding this comment.
This link now needs to be external.
There was a problem hiding this comment.
See commit 958d030
| ``https://courses.edx.org/courses/course-v1:edX+VideoX+1T2016/courseware/ccc7c32c65d342618ac76409254ac238/1a52e689bcec4a9eb9b7da0bf16f682d/`` | ||
|
|
There was a problem hiding this comment.
This long URL looks terrible in RTD. Is there any way to get it to wrap?
PrecisionWordcraft
changed the title
PrecisionWordcraft
changed the title
|
Should this matrix be brought over to the new docs? https://edx.readthedocs.io/projects/edx-developer-guide/en/latest/extending_platform/extending.html |
| You can `download files for that application <http://files.edx.io/JSInput.zip>`_. | ||
| You must upload these files in Studio to use them in a problem. |
There was a problem hiding this comment.
Link broken in source, per make linkcheck.
There was a problem hiding this comment.
Commented out the paragraph that depends on JSInput.zip being available. See commit 714b345.
| - If you have a single piece of content, such as a single interactive HTML5 animation or problem, and you want to use it in an Open edX course, you can create it as a `custom JavaScript application`_. Unlike XBlocks, these applications can be implemented without intervention by the Open edX operator. | ||
| * - **External Graders** | ||
| - Hold, Stable | ||
| - An external grader is a service that receives learner responses to a problem, processes those responses, and returns feedback and a problem grade to the edX platform. You build and deploy an external grader separately from the edX platform. An external grader is particularly useful for software programming courses where learners are asked to submit complex code. See the `external grader documentation`_ for details. |
There was a problem hiding this comment.
Link broken in source per make linkcheck.
There was a problem hiding this comment.
There was a problem hiding this comment.
@robrap Are the links provided by Braden a job for intersphinx?
There was a problem hiding this comment.
Sure. For the reasthedocs links. For this, you could add a mapping for open-edx-building-and-running-a-course.
There was a problem hiding this comment.
Sure. For the reasthedocs links. For this, you could add a mapping for open-edx-building-and-running-a-course.
See commit 42b102d
There was a problem hiding this comment.
New link seems to be https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/en/latest/exercises_tools/external_graders.html
Here's my conf.py setup as of right now:
def edx_rtd_url(slug):
"""Use this with the readthedoc project slug to create the full URL."""
return f"https://edx.readthedocs.io/projects/{slug}/en/latest/"
intersphinx_mapping = {
"openreleasenotes" : (edx_rtd_url("open-edx-release-notes"), None),
"building_running_course" : (edx_rtd_url("open-edx-building-and-running-a-course"), None),
"xblock_tutorial" : (edx_rtd_url("xblock-tutorial"), None)
}
The ref external grader documentation_ gets built as https://edx.readthedocs.io/projects/open-edx-ca/en/latest/exercises_tools/external_graders.html, which results in our "maze (not found)" page.
I don't know how to run down this error.
| Plugins can also inject custom data into django template contexts, to affect standard pages delivered by the core platform. See `Plugin Contexts`_ to learn more. | ||
| * - Course tab (``openedx.course_tab``) |
There was a problem hiding this comment.
Link broken in source per make linkcheck.
There was a problem hiding this comment.
New URL for plugin contexts: https://github.com/edx/edx-django-utils/blob/master/edx_django_utils/plugins/docs/decisions/0001-plugin-contexts.rst
| - A "Learning Context" is a course, a library, a program, a blog, an external site, or some other collection of content where learning happens. If you are trying to build a totally new learning experience that's not a type of course, you may need to implement a new learning context. Learning contexts are a new abstraction and are only supported in the nascent Blockstore-based XBlock runtime. Since existing courses use modulestore instead of Blockstore, they are not yet implemented as learning contexts. However, Blockstore-based content libraries are. See |learning_context.py|_ to learn more. | ||
| * - User partition scheme (``openedx.user_partition_scheme`` and ``openedx.dynamic_partition_generator``) | ||
| - Unknown, Stable | ||
| - A user partition scheme is a named way for dividing users in a course into groups, usually to show different content to different users or to run experiments. Partitions may be added to a course manually, or automatically added by a "dynamic partition generator." The core platform includes partition scheme plugins like ``random``, ``cohort``, and ``enrollment_track``. See the |UserPartition docstring|_ to learn more. |
There was a problem hiding this comment.
Link broken in source per make linkcheck.
There was a problem hiding this comment.
Which link? The "UserPartition docstring" link is working fine for me when I test it at https://draft-edx-developer-docs.readthedocs.io/en/latest/extending/overview_extending.html
|
|
||
| Methods for theming MFEs are still being developed. It is likely to involve: | ||
|
|
||
| #. Branding: modifying fonts, colors, and logos via themes/css (there is an |example edx theme|_ that you can use as a template for defining fonts and colors, but some MFEs currently lack a mechanism for changing the theme). |
There was a problem hiding this comment.
Link broken in source per make linkcheck.
There was a problem hiding this comment.
New text/link should be: "there is a base Open edX theme that you can use..."
| Theming micro-frontends | ||
| ======================= | ||
|
|
||
| *Status: Trial, Limited* | ||
|
|
||
| Methods for theming MFEs are still being developed. It is likely to involve: | ||
|
|
||
| #. Branding: modifying fonts, colors, and logos via themes/css (there is an |example edx theme|_ that you can use as a template for defining fonts and colors, but some MFEs currently lack a mechanism for changing the theme). |
There was a problem hiding this comment.
Is "theming micro-frontends" still considered to be in "trial, limited" status? There's a whole topic on micro-frontends in the "new" developer documentation that's publicly available right now.
I would suggest moving some or all of this content to the micro-frontends topic and linking to that topic from within this section.
|
@bradenmacdonald: Would you be able to review the docs that your extensions doc had pointed to see what is up-to-date, and what should be removed? Thank you! We want to err on removing old documentation that is not valuable. |
…urpose of the file
… into that file; adding two image files to which the XBlock HTML section refers; updating links to XBlock tutorial and Building and Running a Course
now appear both in common tech and in extensions. It's relevant to both.
within this section
javascript file and removing js_template_example
mind about including micro-frontends in the TOC for extending, and removed it.
topic in extension overview
…g_platform\extending.rst to overview_extending topic
robrap
force-pushed
the
PrecisionWordcraft/add_extensions
branch
from
5054cb8
to
46ea90c
Compare
There was a problem hiding this comment.
@robrap Sure. I'm not sure of anything that should be removed, but I did look over the (surprisingly large) number of broken links and provide the newer URLs for them. In most cases things were just moved, not removed.
|
|
||
| Open edX platform development follows the `Open-Closed Principle`_: we offer an extensible platform that allows developers to build extensions that integrate with the core. This allows the core to remain small while volatile extensions remain in the periphery. | ||
|
|
||
| As you will see in this document, there are many different ways to integrate with Open edX. However, we know that there are still some features and integrations that are not possible today without modifying the core. If you have such a need, please consider proposing a new extension point in the core that would make possible the functionality you have in mind. When you submit a pull request for a new extension point, be sure to include a change to this file to document your new extension point. (Doing so will also notify reviewers that want to help with making the platform more extensible.) |
There was a problem hiding this comment.
When you submit a pull request for a new extension point, be sure to include a change to this file to document your new extension point. (Doing so will also notify reviewers that want to help with making the platform more extensible.)
If this is moved out of edx-platform, this sentence will need to be re-worded to say "When you submit a pull request for a new extension point, please open a simultaneous pull request to this documentation to document your new extension point. (Doing so will notify..." and include a link to edit the .rst source file
There was a problem hiding this comment.
@robrap I'm going to assume that we're moving this file out of edx-platform so I'm going to go ahead with this suggested change.
| - If you have a single piece of content, such as a single interactive HTML5 animation or problem, and you want to use it in an Open edX course, you can create it as a `custom JavaScript application`_. Unlike XBlocks, these applications can be implemented without intervention by the Open edX operator. | ||
| * - **External Graders** | ||
| - Hold, Stable | ||
| - An external grader is a service that receives learner responses to a problem, processes those responses, and returns feedback and a problem grade to the edX platform. You build and deploy an external grader separately from the edX platform. An external grader is particularly useful for software programming courses where learners are asked to submit complex code. See the `external grader documentation`_ for details. |
There was a problem hiding this comment.
| Plugins can also inject custom data into django template contexts, to affect standard pages delivered by the core platform. See `Plugin Contexts`_ to learn more. | ||
| * - Course tab (``openedx.course_tab``) |
There was a problem hiding this comment.
New URL for plugin contexts: https://github.com/edx/edx-django-utils/blob/master/edx_django_utils/plugins/docs/decisions/0001-plugin-contexts.rst
| - A "Learning Context" is a course, a library, a program, a blog, an external site, or some other collection of content where learning happens. If you are trying to build a totally new learning experience that's not a type of course, you may need to implement a new learning context. Learning contexts are a new abstraction and are only supported in the nascent Blockstore-based XBlock runtime. Since existing courses use modulestore instead of Blockstore, they are not yet implemented as learning contexts. However, Blockstore-based content libraries are. See |learning_context.py|_ to learn more. | ||
| * - User partition scheme (``openedx.user_partition_scheme`` and ``openedx.dynamic_partition_generator``) | ||
| - Unknown, Stable | ||
| - A user partition scheme is a named way for dividing users in a course into groups, usually to show different content to different users or to run experiments. Partitions may be added to a course manually, or automatically added by a "dynamic partition generator." The core platform includes partition scheme plugins like ``random``, ``cohort``, and ``enrollment_track``. See the |UserPartition docstring|_ to learn more. |
There was a problem hiding this comment.
Which link? The "UserPartition docstring" link is working fine for me when I test it at https://draft-edx-developer-docs.readthedocs.io/en/latest/extending/overview_extending.html
|
|
||
| Methods for theming MFEs are still being developed. It is likely to involve: | ||
|
|
||
| #. Branding: modifying fonts, colors, and logos via themes/css (there is an |example edx theme|_ that you can use as a template for defining fonts and colors, but some MFEs currently lack a mechanism for changing the theme). |
There was a problem hiding this comment.
New text/link should be: "there is a base Open edX theme that you can use..."
Adding an intersphinx mapping for open-edx-building-and-running-a-course per #37 (comment)
I've brought the matrix over. |
Adding intersphinx slug for xblock-tutorial and correcting the slug for building-and-running-a-course
Changing link to XBlock tutorial to an intersphinx ref per #37 (comment)
|
Closing until this work gets picked up again, as documented in https://openedx.atlassian.net/wiki/spaces/AC/pages/2624553266/Developer+Docs+Framework+Notes |
Description:
This "chapter" of the dev docs "book" contains material, or links to material, related to extending the platform: XBlocks, JavaScript apps, and so on.
The consensus is that the extension possibilities are outlined quite nicely in edx-platform/blob/master/docs/guides/extension_points.rst, and that file was copied into this repository. It will eventually be DELETED from its current home and we will need guidance on how best to detect other files that link to it there.
Material on XBlocks and JavaScript was copied in from
edx-documentation/tree/master/en_us/developers/source/extending_platform/.I'd like reviewers to focus on:
See this PR as a draft in readthdocs.
Merge checklist:
Post merge: