From 9e4c448b79649e0931fd046d026cbeacddcbc81c Mon Sep 17 00:00:00 2001 From: Emad Rad Date: Mon, 22 Apr 2024 15:10:37 +0330 Subject: [PATCH] docs: cleanup - rst header definitions fixed - code-blocks added for better readability - tCRIL -> Axim --- README.rst | 58 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 43 insertions(+), 15 deletions(-) diff --git a/README.rst b/README.rst index 5ac263c..81d2284 100644 --- a/README.rst +++ b/README.rst @@ -40,7 +40,7 @@ To check what the current value of `MFE_HOST` is actually set to, run:: tutor config printvalue MFE_HOST Authn -~~~~~~~~~ +~~~~~ .. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/authn.png :alt: Authn MFE screenshot @@ -112,7 +112,7 @@ ORA Grading When enabled, Open Response Assessments ("ORA") that have a staff grading step will link to this new MFE, either when clicking "Grade Available Responses" from the exercise itself, or via a link in the Instructor Dashboard. It is meant to streamline the grading process with better previews of submitted content. Profile -~~~~~~~~~ +~~~~~~~ .. image:: https://raw.githubusercontent.com/overhangio/tutor-mfe/master/screenshots/profile.png :alt: Profile MFE screenshot @@ -131,7 +131,9 @@ Adding new MFEs - As of Tutor v16 (Palm release) it is no longer possible to add new MFEs by creating ``*_MFE_APP`` settings. Instead, users must implement the approach described below. - As of Tutor v17 (Quince release) you must make sure that the git URL of your MFE repository ends with ``.git``. Otherwise the plugin build will fail. -Other MFE developers can take advantage of this plugin to deploy their own MFEs. To declare a new MFE, create a Tutor plugin and add your MFE configuration to the ``tutormfe.hooks.MFE_APPS`` filter. This configuration should include the name, git repository (and optionally: git branch or tag) and development port. For example:: +Other MFE developers can take advantage of this plugin to deploy their own MFEs. To declare a new MFE, create a Tutor plugin and add your MFE configuration to the ``tutormfe.hooks.MFE_APPS`` filter. This configuration should include the name, git repository (and optionally: git branch or tag) and development port. For example: + +.. code-block:: python from tutormfe.hooks import MFE_APPS @@ -151,8 +153,9 @@ Assets will be served at ``http(s)://{{ MFE_HOST }}/mymfe``. Developers are free Disabling individual MFEs ~~~~~~~~~~~~~~~~~~~~~~~~~ -To disable an existing MFE, remove the corresponding entry from the ``MFE_APPS`` filter. For instance, to disable some of the MFEs that ship with this plugin:: +To disable an existing MFE, remove the corresponding entry from the ``MFE_APPS`` filter. For instance, to disable some of the MFEs that ship with this plugin: +.. code-block::python @MFE_APPS.add() def _remove_some_my_mfe(mfes): @@ -172,7 +175,9 @@ This plugin makes it possible to change existing and add new translation strings mkdir account touch account/fr.json -3. Add your entries to this file in JSON format, where the key is the string ID and the value is the actual string. For instance:: +3. Add your entries to this file in JSON format, where the key is the string ID and the value is the actual string. For instance: + +.. code-block::json { "account.settings.section.account.information": "Information du compte" @@ -191,7 +196,8 @@ Customising MFEs .. _mfe-lms-settings: To change the MFEs logos from the default to your own logos, override the corresponding settings in the MFEs environment using patches `mfe-lms-production-settings` and `mfe-lms-development-settings`. For example, using the following plugin: -:: + +.. code-block::python from tutor import hooks @@ -218,12 +224,13 @@ To change the MFEs logos from the default to your own logos, override the corres ] ) -If patches are the same in development and production, they can be replaced by a single `mfe-lms-common-settings` patch. +If patches are the same in development and production, they can be replaced by a single ``mfe-lms-common-settings`` patch. .. _mfe-docker-post-npm-install: To install custom components for the MFEs, such as the `header `_ and `footer `_, override the components by adding a patch to ``mfe-dockerfile-post-npm-install`` in your plugin: -:: + +.. code-block::python from tutor import hooks @@ -240,7 +247,8 @@ To install custom components for the MFEs, such as the `header `_ package: -:: + +.. code-block::python hooks.Filters.ENV_PATCHES.add_item( ( @@ -251,7 +259,9 @@ The same applies to installing a custom `brand `_, you might also need to provide a token for your registry, which can be done with an additional ``npm config set`` command as well: -:: + +.. code-block::python from tutor import hooks @@ -395,44 +407,52 @@ Finally, restart the platform with:: Template patch catalog ---------------------- -This is the list of all patches used across tutor-mfe (outside of any plugin). Alternatively, you can search for patches in tutor-mfe templates by grepping the source code:: - +This is the list of all patches used across tutor-mfe (outside of any plugin). Alternatively, you can search for patches in tutor-mfe templates by grepping the source code: + +.. code-block::python + git clone https://github.com/overhangio/tutor-mfe cd tutor-mfe git grep "{{ patch" -- tutormfe/templates mfe-lms-development-settings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Python-formatted LMS settings in development. Values defined here override the values from `mfe-lms-common-settings <#mfe-lms-common-settings>`_ or `mfe-lms-production-settings <#mfe-lms-production-settings>`_. For an example on the usage of this patch, check out `this section <#mfe-lms-settings>`_. File changed: ``apps/openedx/settings/lms/development.py`` mfe-lms-production-settings ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Python-formatted LMS settings in production. Values defined here override the values from `mfe-lms-common-settings <#mfe-lms-common-settings>`_. For an example on the usage of this patch, check out `this section <#mfe-lms-settings>`_. File changed: ``apps/openedx/settings/lms/production.py`` mfe-lms-common-settings ~~~~~~~~~~~~~~~~~~~~~~~ + Python-formatted LMS settings used both in production and development. File changed: ``apps/openedx/settings/partials/common_lms.py`` mfe-webpack-dev-config ~~~~~~~~~~~~~~~~~~~~~~ + Add any configurations at the end of the development webpack config file in Javascript format. File changed: ``tutormfe/templates/mfe/apps/mfe/webpack.dev-tutor.config.js`` mfe-dockerfile-pre-npm-install ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions for before the npm install is initiated. File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-dockerfile-pre-npm-install-{} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions for before the npm install is initiated for a specific MFE. Add the exact MFE name at the end to only change instructions for that MFE. Example: ``mfe-dockerfile-pre-npm-install-learning`` will only apply any instructions specified for the learning MFE. @@ -441,18 +461,21 @@ File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-dockerfile-production-final ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions in the final layer. Useful for overriding the CMD or ENTRYPOINT. File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-dockerfile-post-npm-install ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions for after the npm install has completed. This will apply the instructions to every MFE. For an example on the usage of this patch, check out `here <#mfe-docker-post-npm-install>`_. File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-dockerfile-post-npm-install-{} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions for after the npm install has completed for a specific MFE. Add the exact MFE name at the end to only change instructions for that MFE. For an example on the usage of this patch, check out `here <#mfe-docker-post-npm-install>`_. Example: ``mfe-dockerfile-post-npm-install-authn`` will only apply any instructions specified for the authn MFE. @@ -461,12 +484,14 @@ File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-dockerfile-pre-npm-build ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions for before the build step initializes. This will apply the instructions to every MFE. For an example on the usage of this patch, see `over here <#mfe-docker-pre-npm-build>`_. File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-dockerfile-pre-npm-build-{} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions for before the build step initializes for a specific MFE. Add the exact MFE name at the end to only change instructions for that MFE. For an example on the usage of this patch, see `over here <#mfe-docker-pre-npm-build>`_. Example: ``mfe-dockerfile-post-npm-build-learning`` will only apply any instructions specified for the learning MFE. @@ -475,12 +500,14 @@ File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-dockerfile-post-npm-build ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions for after the build step has completed. This will apply the instructions to every MFE. File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-dockerfile-post-npm-build-{} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Add any instructions for after the build step has completed for a specific MFE. Add the exact MFE name at the end to only change instructions for that MFE. Example: ``mfe-dockerfile-post-npm-build-learning`` will only apply any instructions specified for the learning MFE. @@ -489,6 +516,7 @@ File changed: ``tutormfe/templates/mfe/build/mfe/Dockerfile`` mfe-caddyfile ~~~~~~~~~~~~~ + Add any configurations for the mfe-caddyfile. File changed: ``tutormfe/templates/mfe/apps/mfe/Caddyfile`` @@ -497,7 +525,7 @@ File changed: ``tutormfe/templates/mfe/apps/mfe/Caddyfile`` Troubleshooting --------------- -This Tutor plugin is maintained by Adolfo Brandes from `tCRIL `__. Community support is available from the official `Open edX forum `__. Do you need help with this plugin? See the `troubleshooting `__ section from the Tutor documentation. +This Tutor plugin is maintained by Adolfo Brandes from `Axim `__. Community support is available from the official `Open edX forum `__. Do you need help with this plugin? See the `troubleshooting `__ section from the Tutor documentation. License -------