-
Notifications
You must be signed in to change notification settings - Fork 15
docs: correct stale config names and paths in paragon README #67
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -120,23 +120,26 @@ Core Plugin Settings | |||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| All configuration variables are defined via Tutor: | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| +----------------------------+--------------------------------------------------------------+-------------------------------+ | ||||||||||||||||||||||||
| | Variable | Description | Default Value | | ||||||||||||||||||||||||
| +============================+==============================================================+===============================+ | ||||||||||||||||||||||||
| | `PARAGON_THEMES_PATH` | Base path for theme sources and compiled output | `env/plugins/paragon/themes` | | ||||||||||||||||||||||||
| +----------------------------+--------------------------------------------------------------+-------------------------------+ | ||||||||||||||||||||||||
| | `PARAGON_THEMES` | List of theme folders to compile and serve | `['light', 'dark']` | | ||||||||||||||||||||||||
| +----------------------------+--------------------------------------------------------------+-------------------------------+ | ||||||||||||||||||||||||
| | `MFE_HOST_EXTRA_FILES` | Whether to serve compiled themes via Tutor’s MFE web server | `true` | | ||||||||||||||||||||||||
| +----------------------------+--------------------------------------------------------------+-------------------------------+ | ||||||||||||||||||||||||
| ``PARAGON_THEME_SOURCES_PATH`` | ||||||||||||||||||||||||
| Base path for theme sources. Default: ``env/plugins/paragon/theme-sources``. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| ``PARAGON_COMPILED_THEMES_PATH`` | ||||||||||||||||||||||||
| Base path for compiled output. Default: ``env/plugins/paragon/compiled-themes``. | ||||||||||||||||||||||||
|
Comment on lines
+126
to
+127
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Matches
👍 |
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| ``PARAGON_ENABLED_THEMES`` | ||||||||||||||||||||||||
| List of theme folders to compile and serve. Default: ``[]``. | ||||||||||||||||||||||||
|
Comment on lines
+129
to
+130
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Matches
and the "theme folders to compile" matches Lines 34 to 39 in 0ca0e46
but the "and serve" is a little misleading because of openedx-tutor-plugins/plugins/tutor-contrib-paragon/tutorparagon/patches/mfe-k8s-volumes Line 1 in 0ca0e46
Line 1 in 0ca0e46
Line 2 in 0ca0e46
Line 2 in 0ca0e46
Not sure the best way to address this, and this is better than the definitely incorrect |
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| ``MFE_HOST_EXTRA_FILES`` | ||||||||||||||||||||||||
| Whether to serve compiled themes via Tutor's MFE web server. Default: ``true``. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Sample Configuration | ||||||||||||||||||||||||
| -------------------- | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| .. code-block:: yaml | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| PARAGON_THEMES_PATH: "{{ TUTOR_ROOT }}/env/plugins/paragon/themes" | ||||||||||||||||||||||||
| PARAGON_THEMES: | ||||||||||||||||||||||||
| PARAGON_THEME_SOURCES_PATH: "env/plugins/paragon/theme-sources" | ||||||||||||||||||||||||
| PARAGON_COMPILED_THEMES_PATH: "env/plugins/paragon/compiled-themes" | ||||||||||||||||||||||||
| PARAGON_ENABLED_THEMES: | ||||||||||||||||||||||||
| - light | ||||||||||||||||||||||||
| - dark | ||||||||||||||||||||||||
| MFE_HOST_EXTRA_FILES: true | ||||||||||||||||||||||||
|
|
@@ -146,20 +149,21 @@ Theme Directory Structure | |||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| .. code-block:: text | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ | ||||||||||||||||||||||||
| ├── core/ # Shared base design tokens | ||||||||||||||||||||||||
| ├── light/ # Light theme tokens | ||||||||||||||||||||||||
| └── dark/ # Dark theme tokens | ||||||||||||||||||||||||
| $(tutor config printroot)/env/plugins/paragon/theme-sources/ | ||||||||||||||||||||||||
| ├── core/ # Shared base design tokens | ||||||||||||||||||||||||
| └── themes/ | ||||||||||||||||||||||||
| ├── light/ # Light theme tokens | ||||||||||||||||||||||||
| └── dark/ # Dark theme tokens | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Only themes listed in `PARAGON_THEMES` will be compiled and served. The `core/` directory is required and provides base styles shared across all themes. | ||||||||||||||||||||||||
| Only themes listed in `PARAGON_ENABLED_THEMES` will be compiled and served. The `core/` directory is required and provides base styles shared across all themes. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Usage | ||||||||||||||||||||||||
| ===== | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Build All Themes | ||||||||||||||||||||||||
| ---------------- | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| To compile all themes listed in `PARAGON_THEMES`: | ||||||||||||||||||||||||
| To compile all themes listed in `PARAGON_ENABLED_THEMES`: | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| .. code-block:: bash | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
|
|
@@ -187,7 +191,7 @@ Output | |||||||||||||||||||||||
| ------ | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Compiled CSS files (minified `.min.css`) are written to: | ||||||||||||||||||||||||
| {{ TUTOR_ROOT }}/env/plugins/paragon/themes/<theme>/<theme>.min.css | ||||||||||||||||||||||||
| $(tutor config printroot)/env/plugins/paragon/compiled-themes/themes/<theme>/<theme>.min.css | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Static Hosting | ||||||||||||||||||||||||
| ============== | ||||||||||||||||||||||||
|
|
@@ -202,7 +206,7 @@ Example URLs: | |||||||||||||||||||||||
| * Local LMS: `http://apps.local.openedx.io/static/paragon/themes/light/light.min.css` | ||||||||||||||||||||||||
| * Dev server: `http://localhost:<PORT>/static/paragon/themes/dark/dark.min.css` | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Each theme listed in `PARAGON_THEMES` is automatically exposed for use in MFEs. | ||||||||||||||||||||||||
| Each theme listed in `PARAGON_ENABLED_THEMES` is automatically exposed for use in MFEs. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Updating Theme Configuration | ||||||||||||||||||||||||
| ============================ | ||||||||||||||||||||||||
|
|
@@ -215,7 +219,7 @@ Use `tutor config save --set` to update your variables. For example: | |||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| .. code-block:: bash | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| tutor config save --set PARAGON_THEMES='["light", "dark"]' | ||||||||||||||||||||||||
| tutor config save --set PARAGON_ENABLED_THEMES='["light", "dark"]' | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| 2. **Restart the development environment** | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
|
|
@@ -270,18 +274,18 @@ You can host the base Paragon styles yourself using this plugin's static file ho | |||||||||||||||||||||||
| **💡 Note:** | ||||||||||||||||||||||||
| MFEs within the same Open edX release typically use the same major version of Paragon, but minor versions might differ. You can check the version for an MFE by inspecting its ``package.json`` file or running ``npm list @openedx/paragon`` within an MFE directory. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| 2. Place the base CSS file(s) into your ``PARAGON_THEMES_PATH`` directory. You have two main options for structuring this: | ||||||||||||||||||||||||
| 2. Place the base CSS file(s) into your ``PARAGON_COMPILED_THEMES_PATH`` directory. You have two main options for structuring this: | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| * **Host a single version:** If all your MFEs can use the same version (e.g., the latest minor of a major version like ``23.4.0``), place it once:: | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ | ||||||||||||||||||||||||
| $(tutor config printroot)/env/plugins/paragon/compiled-themes/ | ||||||||||||||||||||||||
| └── core/ | ||||||||||||||||||||||||
| └── 23.4.0/ # A single, chosen version | ||||||||||||||||||||||||
| └── core.min.css | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| * **Host multiple versions:** To support MFEs using different Paragon versions, create a directory structure for each required version:: | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ | ||||||||||||||||||||||||
| $(tutor config printroot)/env/plugins/paragon/compiled-themes/ | ||||||||||||||||||||||||
| └── core/ | ||||||||||||||||||||||||
| ├── 23.1.0/ # Version for MFE A | ||||||||||||||||||||||||
| │ └── core.min.css | ||||||||||||||||||||||||
|
|
@@ -321,7 +325,7 @@ For more detailed information on MFE theming and loading external styles, refer | |||||||||||||||||||||||
| Troubleshooting | ||||||||||||||||||||||||
| =============== | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| * **Themes not compiled**: Ensure theme folders exist and match names in `PARAGON_THEMES`. | ||||||||||||||||||||||||
| * **Themes not compiled**: Ensure theme folders exist and match names in `PARAGON_ENABLED_THEMES`. | ||||||||||||||||||||||||
| * **Permission errors**: Verify Docker and Tutor have write access to the themes directory. | ||||||||||||||||||||||||
| * **Missing core tokens**: Ensure the `core/` folder exists and contains valid token files. | ||||||||||||||||||||||||
| * **Error: "Expected at least 4 args"**: Always run builds via `tutor local do`, not inside containers. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Matches
openedx-tutor-plugins/plugins/tutor-contrib-paragon/tutorparagon/plugin.py
Line 24 in 0ca0e46
👍