Skip to content

docs: update the README with dev docs #46

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.

Sign up for GitHub

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

Merged
merged 7 commits into from
Jul 30, 2025
Merged

docs: update the README with dev docs #46

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
687d76b
docs: update the README with dev docs
tecoholic Jun 25, 2025
449fcac
docs: fix spacing issue
tecoholic Jun 25, 2025
0cd8df7
docs: add sytanx highlighting hints
tecoholic Jun 25, 2025
e9dbdd1
fix: add missing commands
tecoholic Jul 3, 2025
ea4c615
docs: remove legacy peer deps from install instructions
tecoholic Jul 29, 2025
940c3d2
Merge branch 'main' into tecoholic/update-readme
tecoholic Jul 30, 2025
136faad
Update README.rst
farhaanbukhsh Jul 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 179 additions & 22 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,56 +3,213 @@ frontend-plugin-aspects

|license-badge| |status-badge| |ci-badge| |codecov-badge|

.. |license-badge| image:: https://img.shields.io/github/license/openedx/frontend-app-[PLACEHOLDER].svg
:target: https://github.com/openedx/frontend-app-[PLACEHOLDER]/blob/main/LICENSE
.. |license-badge| image:: https://img.shields.io/github/license/openedx/frontend-plugin-aspects.svg
:target: https://github.com/openedx/frontend-plugin-aspects/blob/main/LICENSE
:alt: License

.. |status-badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen

.. |ci-badge| image:: https://github.com/openedx/frontend-app-[PLACEHOLDER]/actions/workflows/ci.yml/badge.svg
:target: https://github.com/openedx/frontend-app-[PLACEHOLDER]/actions/workflows/ci.yml
.. |ci-badge| image:: https://github.com/openedx/frontend-plugin-aspects/actions/workflows/ci.yml/badge.svg
:target: https://github.com/openedx/frontend-plugin-aspects/actions/workflows/ci.yml
:alt: Continuous Integration

.. |codecov-badge| image:: https://codecov.io/github/openedx/frontend-app-[PLACEHOLDER]/coverage.svg?branch=main
:target: https://codecov.io/github/openedx/frontend-app[PLACEHOLDER]?branch=main
.. |codecov-badge| image:: https://codecov.io/github/openedx/frontend-plugin-aspects/coverage.svg?branch=main
:target: https://codecov.io/github/openedx/frontend-plugin-aspects?branch=main
:alt: Codecov

Purpose
=======

This is a collection of components meant to integrate Apects into the the
pltform UI.
This is a collection of components meant to integrate Apects into the platform UI. They are presently used in on the sidebar slots of the Authoring MFE.


Getting Started
===============

Configuration
-------------

The components are added to the Authoring MFE when `tutor-contrib-aspects`_ is used in a Tutor deployment.

.. _tutor-contrib-aspects: https://github.com/openedx/tutor-contrib-aspects


Development Setup
-----------------

1. Install `tutor-contrib-aspects`_ and rebuild the edx-platform image

.. code-block:: sh

pip install tutor-contrib-aspects
tutor plugin enable aspects
tutor config save --set ASPECTS_ENABLE_STUDIO_IN_CONTEXT_METRICS=True
tutor images build openedx --no-cache
tutor images build aspects aspects-superset

2. Clone *frontend-app-authoring*

.. code-block:: sh

git clone https://github.com/openedx/frontend-app-authoring.git

3. Clone this repo inside *frontend-app-authoring* and install it

.. code-block::

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe adding https://github.com/openedx/frontend-app-authoring?tab=readme-ov-file#startup here will make the setup simpler

Copy link
Contributor Author

@tecoholic tecoholic Jul 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@farhaanbukhsh I thought about doing it. But I find it hard to switch repo READMEs and modify the just a couple of commands. I end up missing the order of the commands and having to redo it. So, I thought I will document everything here in order, so we can just follow a single readme.

cd frontend-app-authoring
git clone https://github.com/openedx/frontend-plugin-aspects.git
npm install ./frontend-plugin-aspects

4. Create/Update the ``env.config.jsx`` file inside ``frontend-app-authoring`` with the slot definitions

.. code-block:: jsx

import { PLUGIN_OPERATIONS, DIRECT_PLUGIN } from "@openedx/frontend-plugin-framework";
import {
SidebarToggleWrapper,
CourseHeaderButton,
UnitActionsButton,
AspectsSidebarProvider,
CourseOutlineSidebar,
UnitPageSidebar,
SubSectionAnalyticsButton,
} from "@openedx/frontend-plugin-aspects";

const config = {
...process.env,
pluginSlots: {
"org.openedx.frontend.authoring.course_outline_sidebar.v1": {
keepDefault: true,
plugins: [
{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: "outline-sidebar",
priority: 1,
type: DIRECT_PLUGIN,
RenderWidget: CourseOutlineSidebar,
},
},
{
op: PLUGIN_OPERATIONS.Wrap,
widgetId: "default_contents",
wrapper: SidebarToggleWrapper,
},
],
},
"org.openedx.frontend.authoring.course_unit_sidebar.v2": {
keepDefault: true,
plugins: [
{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: "course-unit-sidebar",
priority: 1,
type: DIRECT_PLUGIN,
RenderWidget: UnitPageSidebar,
},
},
{
op: PLUGIN_OPERATIONS.Wrap,
widgetId: "default_contents",
wrapper: SidebarToggleWrapper,
},
],
},
"org.openedx.frontend.authoring.course_outline_header_actions.v1": {
keepDefault: true,
plugins: [
{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: "outline-analytics",
type: DIRECT_PLUGIN,
priority: 51,
RenderWidget: CourseHeaderButton,
},
},
],
},
"org.openedx.frontend.authoring.course_unit_header_actions.v1": {
keepDefault: true,
plugins: [
{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: "unit-analytics",
type: DIRECT_PLUGIN,
priority: 51,
RenderWidget: CourseHeaderButton,
},
},
],
},
"org.openedx.frontend.authoring.course_outline_unit_card_extra_actions.v1":
{
keepDefault: true,
plugins: [
{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: "uni-card-my-extra-action",
type: DIRECT_PLUGIN,
priority: 51,
RenderWidget: UnitActionsButton,
},
},
],
},
"org.openedx.frontend.authoring.course_outline_subsection_card_extra_actions.v1":
{
keepDefault: true,
plugins: [
{
op: PLUGIN_OPERATIONS.Insert,
widget: {
id: "sub-card-my-extra-action",
type: DIRECT_PLUGIN,
priority: 51,
RenderWidget: SubSectionAnalyticsButton,
},
},
],
},
},
};

export default config;


5. Add Authoring MFE source as a tutor mount and rebuild the MFE images

.. code-block:: sh

tutor mounts add /path/to/frontend-app-authoring
tutor images build mfe --no-cache

6. Start the services using ``turor dev launch``, which should setup everything have the services running.
7. Edit the code in ``frontend-plugin-aspects`` to make changes and then run ``npm run build`` to update the MFE.

.. note::

[TODO]
As ``npm run build`` needs to be run before changes are reflected in the UI, it is recommended
to use a file watcher like `nodemon`_ to automate this.

Known Issues
============
For example: ``nodemon --watch src --exec "npm run build"``

.. note::

[TODO]
.. _nodemon: https://nodemon.io

If there are long-standing known issues, list them here as a bulletted list,
linking to the actual issues in the Github repository.
Known Issues
============

N/A

Development Roadmap
===================

.. note::

[TODO]

Include a list of current development targets, in (rough) descending order
of priority. It can be a simple bulleted list of roadmap items with links
to Github issues or wiki pages.
N/A

Getting Help
============
Expand Down
Loading