docs: Rewrite and improve plugin documentation #39

maguilarUXUI · 2025-07-24T21:54:36Z

This commit updates the Tutor Paragon Plugin documentation to align with recent code changes and the approach outlined in the original proposal. Key updates include:

Renamed core configuration variables to match the proposal and implementation:
- PARAGON_THEME_SOURCES_PATH and PARAGON_COMPILED_THEMES_PATH are consolidated into PARAGON_THEMES_PATH.
- PARAGON_ENABLED_THEMES is renamed to PARAGON_THEMES.
- PARAGON_SERVE_COMPILED_THEMES is replaced by the tutor-mfe plugin's MFE_HOST_EXTRA_FILES setting.
Updated the theme directory structure description to reflect that themes (including core/) are placed directly within PARAGON_THEMES_PATH.
Corrected the output path for compiled CSS files to PARAGON_THEMES_PATH/<theme>/<theme>.min.css.
Revised the 'Static Hosting' section to accurately describe the plugin's use of the tutor-mfe plugin's MFE_HOST_EXTRA_FILES feature, instead of adding a separate Nginx service.
Added a prerequisite note for the tutor-mfe plugin.
Improved formatting and clarity, including using a table for configuration variables.

Updated structure, added version info, improved examples and linked external docs.

openedx-webhooks · 2025-07-24T21:54:40Z

Thanks for the pull request, @maguilarUXUI!

This repository is currently maintained by @arbrandes.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

maguilarUXUI · 2025-07-24T22:05:38Z

Assign me

maguilarUXUI · 2025-07-24T22:09:50Z

Hi @arbrandes 👋

This PR is ready for review. Let me know if there’s anything I should revise.
Thanks in advance!

mphilbrick211 · 2025-07-29T19:51:39Z

Hi @maguilarUXUI! If you haven't already, please make sure your manager reaches out to [email protected] to have you added to our existing agreement with edunext. Thanks!

…ructure This commit updates the Tutor Paragon Plugin documentation to align with recent code changes and the approach outlined in the original proposal.

maguilarUXUI · 2025-08-26T19:48:49Z

@Ang-m4 The corresponding changes were applied!

Ang-m4

Hi @maguilarUXUI, overall this looks great, thanks for updating the docs for the tutor-mfe integration.

I left a comment regarding the local URLs so they point correctly to the MFE host.

Ang-m4 · 2025-09-01T14:05:50Z

plugins/tutor-contrib-paragon/README.rst


- **Error: "Expected at least 4 args"**  
-  This occurs when the build job is invoked directly inside the container. Always run via Tutor:
+* Local LMS: `http://local.openedx.io/static/paragon/themes/light/light.min.css`


Suggested change

* Local LMS: `http://local.openedx.io/static/paragon/themes/light/light.min.css`

* Local LMS: `http://<MFE_HOST>/static/paragon/themes/light/light.min.css`

Now that the plugin leverages the tutor-mfe host extra files feature, the local URLs should point to the MFE host (by default: apps.local.openedx.io).

Clarifies when to use tutor config save, tutor dev stop, and tutor dev start when updating theme variables. Adds step-by-step instructions to the documentation under the Static Hosting section.

maguilarUXUI · 2025-09-03T19:20:42Z

added changes @brian-smith-tcril @Ang-m4

brian-smith-tcril · 2025-09-11T19:41:40Z

Commenting to see if that kicks off the CLA check.

brian-smith-tcril · 2025-09-11T19:45:42Z

Closing/reopening to kick off the CLA check.

brian-smith-tcril · 2025-09-15T14:51:47Z

Closing/reopening (again) to kick off the CLA check.

sarina · 2025-09-15T15:43:50Z

plugins/tutor-contrib-paragon/README.rst

+
+* **Paragon 23+**
+* **Open edX "Teak" release (or Tutor 20+)**
+* **Tutor 20+**


Should these say "greater than or equal to"? Do we think this plugin will stop working on Tutor 21 or Paragon 24?

My read was that the + implied >=, but I can see how someone might read that as 23.x or 20.x.

The pyproject.toml file currently has a tutor version requirement of tutor>=19.0.0,<21.0.0, and a tutor-mfe requirement of tutor-mfe @ git+https://github.com/overhangio/tutor-mfe.git@release.

The tutor-mfe version requirement should be updated once overhangio/tutor-mfe#267 and overhangio/tutor-mfe#264 make it into releases (as of writing the latest tutor-mfe release is v20.0.0 from June 27th).

I think for the README it makes sense to clearly imply >=, as we should expect to support this plugin beyond Paragon 23 and Tutor 20. That being said, major versions can include breaking changes, so it is quite possible this plugin will need to be updated to support any Tutor 21 or Paragon 23 changes.

…ersion compatibility This commit improves the documentation by: - Adding a new section titled “Loading Base Paragon Styles” to guide site operators on how to optimize performance by using shared styles. - Clarifying version compatibility in the “Version Compatibility” section.

maguilarUXUI · 2025-09-15T20:42:46Z

I added the last changes! @brian-smith-tcril @Ang-m4 @sarina

brian-smith-tcril

Overall this is looking really good!

I left a couple of specific inline comments, and I also noticed a few general things:

I'm not sure all of the formatting (.. note::, .. code-block:: text, etc.) is working as expected. I was checking by reading from https://github.com/maguilarUXUI/openedx-tutor-plugins/tree/patch-1/plugins/tutor-contrib-paragon
This plugin isn't in the table on the main README (https://github.com/maguilarUXUI/openedx-tutor-plugins/tree/patch-1?tab=readme-ov-file#purpose)

plugins/tutor-contrib-paragon/README.rst

sarina · 2025-09-16T14:51:12Z

.. note::, .. code-block:: text, etc. will only work if rendered on ReadTheDocs. I don't think they should be used in READMEs since those are meant to be read on GH.

sarina · 2025-09-16T14:52:34Z

For codeblock you just use this syntax:

::

    code

See https://raw.githubusercontent.com/overhangio/tutor-mfe/refs/heads/release/README.rst

brian-smith-tcril

This looks wonderful!

One tiny comment about some code block formatting, but once that's resolved this should be good to merge!

brian-smith-tcril · 2025-09-23T15:58:03Z

plugins/tutor-contrib-paragon/README.rst


- **Themes are not picked up when using --themes:**  
-  The value for ``--themes`` must be a comma-separated list (no spaces), e.g. ``--themes theme-1,theme-2``.
+        ``https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css``


The formatting here looks odd (the `` are rendering in the block)

brian-smith-tcril

Perfect!

Thank you so much for putting this together!

docs: Rewrite and improve plugin documentation

310ed54

Updated structure, added version info, improved examples and linked external docs.

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Jul 24, 2025

openedx-webhooks added this to Contributions Jul 24, 2025

github-project-automation bot moved this to Needs Triage in Contributions Jul 24, 2025

github-actions bot assigned maguilarUXUI Jul 24, 2025

mphilbrick211 moved this from Needs Triage to Needs Tests Run or CLA Signed in Contributions Jul 29, 2025

mphilbrick211 added the needs test run Author's first PR to this repository, awaiting test authorization from Axim label Jul 29, 2025

Ang-m4 mentioned this pull request Jul 31, 2025

docs: add theme hosting and URL configuration documentation eduNEXT/openedx-tutor-plugins#6

Closed

e0d removed the needs test run Author's first PR to this repository, awaiting test authorization from Axim label Aug 4, 2025

docs: Update README.rst to reflect latest plugin configuration and st…

8aae940

…ructure This commit updates the Tutor Paragon Plugin documentation to align with recent code changes and the approach outlined in the original proposal.

mphilbrick211 added the needs test run Author's first PR to this repository, awaiting test authorization from Axim label Aug 27, 2025

Ang-m4 mentioned this pull request Aug 29, 2025

feat: add paragon hosting configuration for dev and local environments (FC-87) #38

Merged

Ang-m4 reviewed Sep 1, 2025

View reviewed changes

docs: Add configuration update steps for theme hosting

00aee00

Clarifies when to use tutor config save, tutor dev stop, and tutor dev start when updating theme variables. Adds step-by-step instructions to the documentation under the Static Hosting section.

brian-smith-tcril mentioned this pull request Sep 10, 2025

Add documentation for loading non-bundled base Paragon styles #44

Closed

mphilbrick211 removed the needs test run Author's first PR to this repository, awaiting test authorization from Axim label Sep 11, 2025

brian-smith-tcril closed this Sep 11, 2025

github-project-automation bot moved this from Needs Tests Run or CLA Signed to Done in Contributions Sep 11, 2025

brian-smith-tcril reopened this Sep 11, 2025

brian-smith-tcril closed this Sep 15, 2025

brian-smith-tcril reopened this Sep 15, 2025

sarina reviewed Sep 15, 2025

View reviewed changes

brian-smith-tcril reviewed Sep 16, 2025

View reviewed changes

plugins/tutor-contrib-paragon/README.rst Outdated Show resolved Hide resolved

plugins/tutor-contrib-paragon/README.rst Outdated Show resolved Hide resolved

plugins/tutor-contrib-paragon/README.rst Show resolved Hide resolved

docs: improve formatting for GitHub compatibility and clarity

5c347cb

brian-smith-tcril reviewed Sep 23, 2025

View reviewed changes

brian-smith-tcril linked an issue Sep 23, 2025 that may be closed by this pull request

Add documentation for loading non-bundled base Paragon styles #44

Closed

docs: improve README.rst - Hide ( `` )

8a24b4a

brian-smith-tcril approved these changes Sep 24, 2025

View reviewed changes

brian-smith-tcril merged commit 9e595c7 into openedx:main Sep 24, 2025
3 checks passed

	* Local LMS: `http://local.openedx.io/static/paragon/themes/light/light.min.css`
	* Local LMS: `http://<MFE_HOST>/static/paragon/themes/light/light.min.css`

docs: Rewrite and improve plugin documentation #39

docs: Rewrite and improve plugin documentation #39

Uh oh!

Conversation

maguilarUXUI commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openedx-webhooks commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maguilarUXUI commented Jul 24, 2025

Uh oh!

maguilarUXUI commented Jul 24, 2025

Uh oh!

mphilbrick211 commented Jul 29, 2025

Uh oh!

maguilarUXUI commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ang-m4 left a comment

Choose a reason for hiding this comment

Uh oh!

Ang-m4 Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

maguilarUXUI commented Sep 3, 2025

Uh oh!

brian-smith-tcril commented Sep 11, 2025

Uh oh!

brian-smith-tcril commented Sep 11, 2025

Uh oh!

brian-smith-tcril commented Sep 15, 2025

Uh oh!

sarina Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

brian-smith-tcril Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

maguilarUXUI commented Sep 15, 2025

Uh oh!

brian-smith-tcril left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarina commented Sep 16, 2025

Uh oh!

sarina commented Sep 16, 2025

Uh oh!

brian-smith-tcril left a comment

Choose a reason for hiding this comment

Uh oh!

brian-smith-tcril Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

brian-smith-tcril left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

maguilarUXUI commented Jul 24, 2025 •

edited

Loading

openedx-webhooks commented Jul 24, 2025 •

edited

Loading

maguilarUXUI commented Aug 26, 2025 •

edited

Loading