richie 3.0.1.dev1__tar.gz → 3.0.1.dev2__tar.gz

{richie-3.0.1.dev1 → richie-3.0.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: richie
-Version: 3.0.1.dev1
+Version: 3.0.1.dev2
 Summary: A CMS to build learning portals for open education
 Author-email: "Open FUN (France Université Numérique)" <fun.dev@fun-mooc.fr>
 License: MIT License

richie-3.0.1.dev2/docs/contributing.md

@@ -0,0 +1,79 @@
+---
+id: contributing-guide
+title: Contributing guide
+sidebar_label: Contributing guide
+---
+
+This project is intended to be community-driven, so please, do not hesitate to get in touch if you have any question related to our implementation or design decisions.
+
+We try to raise our code quality standards and expect contributors to follow the recommandations
+from our [handbook](https://openfun.gitbooks.io/handbook/content).
+
+## Checking your code
+
+We use strict flake8, pylint, isort and black linters to check the validity of our backend code:
+
+```bash
+    $ make lint-back
+```
+
+We use strict eslint and prettier to check the validity of our frontend code:
+
+```bash
+    $ make lint-front
+```
+
+## Running tests
+
+On the backend, we use pytest to run our test suite:
+
+```bash
+    $ make test-back
+```
+
+On the frontend, we use karma to run our test suite:
+
+```bash
+    $ make test-front
+```
+
+## Running migrations
+
+The first time you start the project with `make bootstrap`, the `db` container automatically
+creates a fresh database named `richie` and performs database migrations. Each time a new
+**database migration** is added to the code, you can synchronize the database schema by running:
+
+```bash
+    $ make migrate
+```
+
+## Handling new dependencies
+
+Each time you add new front-end or back-end dependencies, you will need to rebuild the
+application. We recommend to use:
+
+```bash
+    $ make bootstrap
+```
+
+## Going further
+
+To see all available commands, run:
+
+```bash
+    $ make
+```
+
+We also provide shortcuts for docker compose commands as sugar scripts in the
+`bin/` directory:
+
+```
+bin
+├── exec
+├── pylint
+├── pytest
+└── run
+```
+
+More details and tips & tricks can be found in our [development with Docker
+documentation](docker-development.md)

{richie-3.0.1.dev1/website/versioned_docs/version-3.0.0 → richie-3.0.1.dev2/docs}/cookiecutter.md

@@ -90,7 +90,15 @@ committing it and pushing it to a new git repository.
 
 ## Theming
 
-You probably want to change the default theme. The cookiecutter adds an extra scss frontend folder with a couple of templates that you can use to change the default styling of the site.
+You probably want to change the default theme. Design tokens (color, fonts, etc.) are managed
+through our fully customisable design system [Cunningham](https://github.com/openfun/cunningham).
+The cookiecutter adds a `cunningham.cjs` file in the `sites/<site>/src/frontend` folder to 
+allow you to customize the design tokens. Modify or add our design tokens in this file 
+then run `yarn build-theme` to generate sass and css files 
+into `sites/<site>/src/frontend/scss/vendors` folder.
+
+Furthermore the cookiecutter adds an extra scss frontend folder with a couple
+of templates that you can use to change the default styling of the site.
 * `sites/<site>/src/frontend/scss/extras/colors/_palette.scss`
 * `sites/<site>/src/frontend/scss/extras/colors/_theme.scss`
 

richie-3.0.1.dev2/docs/discover.md

@@ -0,0 +1,61 @@
+---
+id: discover
+title: Discover Richie
+sidebar_label: Discover Richie
+---
+
+`Learning Management Systems` (LMS) are great tools for hosting and playing interactive online
+courses and MOOCs.
+
+However, if you need to build a complete website with flexible content to aggregate your courses,
+in several languages and from different sources, **you will soon need a CMS**.
+
+At "France Université Numérique", we wanted to build an OpenSource portal with `Python` and
+`Django`. That's why we built `Richie` on top of [DjangoCMS](https://www.django-cms.org), one of
+the best CMS on the market, as a toolbox to easily create full fledged websites with a catalog of
+online courses.
+
+![screenshot of richie demo site](assets/images/demo-screenshot.jpg)
+
+Among the features that `Richie` offers out of the box:
+
+- multi-lingual by default,
+- advanced access rights and moderation,
+- catalog of courses synchronized with one or more `LMS` instances,
+- search engine based on `Elasticsearch` and pre-configured to offer full-text queries,
+  multi-facetting, auto-complete,...
+- flexible custom pages for courses, organizations, categories, teachers, blog posts,
+  programs (and their inter-relations),
+- Extensible with any third-party `DjangoCMS` plugin or any third-party `Django` application.
+- E-commerce capabilities through [Joanie](https://github.com/openfun/joanie).
+
+## Quick preview
+
+If you're looking for a quick preview of `Richie`, you can take a look and have a tour of
+`Richie` on our dedicated [demo site](https://demo.richie.education).
+
+It is connected back-to-back with a demo of OpenEdX running on
+[OpenEdX Docker](https://github.com/openfun/openedx-docker).
+
+Two users are available for testing:
+
+- admin: `admin@example.com`/`admin`
+- student: `edx@example.com`/`edx`
+
+The database is regularly flushed.
+
+## Start your own site
+
+The next step after discovering Richie on the demo is to start your own project. We provide a
+production-ready template based on [Cookiecutter](https://github.com/audreyr/cookiecutter) that
+allows you to generate your project in seconds.
+
+Follow the guide on [starting your own Richie site with Cookiecutter](./cookiecutter.md).
+
+Once you created a new site, you will be able to fully customize it:
+
+- override any Django template or portion of template,
+- [override ReactJS components](./frontend-overrides.md),
+- override some css rules or rebuild the whole css with your own variables and customizations,
+- add any [DjangoCMS](https://www.django-cms.org) plugin or feature,
+- add any [Django third-party application](https://djangopackages.org).

richie-3.0.1.dev2/docs/django-react-interop.md

@@ -0,0 +1,167 @@
+---
+id: django-react-interop
+title: Connecting React components with Django
+sidebar_label: Django & React
+---
+
+`richie` is a hybrid app, that relies on both HTML pages generated by the backend (Django/DjangoCMS) based on templates, and React components rendered on the frontend for parts of these HTML pages.
+
+## Rendering components
+
+We needed a convention that enables us to easily mark those areas of the page that React needs to take control of, and to tell React which component to load there.
+
+We decided to use a specific CSS class name along with its modifiers. We reserve the `richie-react` class and its modified children for this purpose.
+
+Additionally, components including internationalized data or strings need to know which locale to use. They will pick up the locale specified through the `lang` attribute of the `<html>` element, which is a requirement to have an accessible page anyway.
+
+They use the BCP47/RFC5646 format.
+
+```html
+    <html lang="en-US">
+```
+
+### Example
+
+Here is how we would call a `<FeaturedCourses />` component from a template, a plugin or a snippet:
+
+```html
+    <div
+      class="richie-react richie-react--featured-courses"
+    ></div>
+```
+
+When our JS is loaded, it will recognize this as an element it must take over, and render the FeaturedCourses component in this element.
+
+## Passing properties to components
+
+Some of Richie's React components, and some of those you might want to write, require arguments or "props" to be passed to them. We could work around that by adding API routes to fetch these props, but that would add complexity and reduce performance.
+
+Instead, we decided to normalize a simpler way for components in Richie to accept input from the Django template that is adding them to the DOM.
+
+We can add a `data-props` attribute on the element with the `richie-react` class and write a JSON object as the value for this attribute. Each key-value pair in this object will be passed as a `propName={propValue}` to the React component.
+
+### Example
+
+Here is how we would pass a `categories={[ "sociology", "anthropology" ]}` prop to our `<FeaturedCourses />` component:
+
+```html
+    <div
+      class="richie-react richie-react--featured-courses"
+      data-props='{"categories": ["sociology", "anthropology"]}'
+    ></div>
+```
+
+When the component is rendered, it will be passed a `categories` prop with the relevant categories.
+
+## Built-in components
+
+Here are the React component that Richie comes with and uses out of the box. All available 
+built-in components are available from `src/frontend/js/widgets` folder.
+
+### &lt;RootSearchSuggestField /&gt;
+
+Renders a course search bar, like the one that appears in the default `Search` page.
+
+Interactions will send the user to the `courseSearchPageUrl` url passed in the props, including the selected filter and/or search terms.
+
+It also autocompletes user input with course names and allows users to go directly to the course page if they select a course name among the selected results.
+
+Props:
+
+- `courseSearchPageUrl` [required] — URL for the course search page users should be sent to when they select a suggestion that is not a course, or launch a search with text terms.
+- `context` [required] — see [context](#context).
+
+### &lt;Search /&gt;
+
+Renders the full-page course search engine interface, including the search results, and filters pane, but not the suggest field (which can be added separately with `<SearchSuggestField />`) nor the page title.
+
+NB: the `Search` Django template basically renders just this page. If you need this, use it instead. It is included here for completeness' sake.
+
+Props:
+
+- `context` [required] — see [context](#context).
+
+### &lt;SearchSuggestField /&gt;
+
+Renders the course search bar that interacts directly with `<Search />`.
+
+It automatically communicates with `<Search />` through browser history APIs and a shared React provider. This one, unlike `<RootSearchSuggestField />`, is meant to be used in combination with `<Search />` (on the same page).
+
+Props:
+
+- `context` [required] — see [context](#context).
+
+### &lt;UserLogin /&gt;
+
+Renders a component that uses the `/users/whoami` endpoint to determine if the user is logged in and show them the appropriate interface: Signup/Login buttons or their name along with a Logout button.
+
+Props:
+
+- `loginUrl` [required] — the URL where the user is sent when they click on "Log in";
+- `logoutUrl` [required] — a link that logs the user out and redirects them (can be the standard django logout URL);
+- `signupUrl` [required] — the URL where the user is sent when they click on "Sign up".
+
+### &lt;LanguageSelector /&gt;
+
+Renders a language selector component that allows the user to select their language.
+
+Props:
+
+- `currentLanguage` [required] — the current language of the page
+- `languages` [required] - an object containing all languages available
+
+### &lt;LtiConsumer /&gt;
+
+Renders an iframe through iframe-resizer that embeds a 
+[LTI](https://en.wikipedia.org/wiki/Learning_Tools_Interoperability) tool defined
+through the [`LtiConsumer` plugin](https://github.com/openfun/richie/blob/master/src/richie/plugins/lti_consumer).
+
+Props:
+
+- `id` [required] — the id of the `LtiConsumer` plugin instance
+
+### &lt;Slider /&gt;
+
+Renders a Carousel based on the [`Slider` plugin](https://github.com/openfun/richie/blob/master/src/richie/plugins/slider) .
+
+Props:
+
+- `title` [required] - the title of the slider (use for accessibility purpose)
+- `slides` [required] - an array of slides
+
+### &lt;SyllabusCourseRunsList /&gt;
+
+Renders a list of course runs for a given course. This component is used to display the list of course runs
+on the course syllabus page .
+
+Props:
+
+- `courseRuns` [required] — an array of course runs to render
+- `course` [required] — the course object
+- `maxArchivedCourseRuns` [required] — the maximum number of archived course runs to display. After this limit, a "View more" link is displayed to allow the user to view the remaining course runs.
+
+### &lt;Dashboard /&gt; (*require Joanie*)
+
+This is widget is more a SPA than a simple React component. It is used to renders
+learner and teacher dashboards when using the [Joanie](https://github.com/openfun/joanie)
+platform. It is a big stone of Richie to be multi-lms friendly. It allows
+ to aggregate learner enrollments from Joanie that under hood is linked to
+ several lms.
+
+## Context
+
+All built-in components for Richie accept a `context` prop, that may be required or optional, depending on the component.
+
+It is used to pass app-wide contextual information pertaining to the current instance, deployment or theme of Richie.
+
+Here is the expected shape for this object:
+
+```js
+    {
+        assets: {
+            // SVG sprite used throughout Richie
+            icons: "/path/to/icons/sprite.svg"
+        }
+    }
+```
+Note that it might be expanded in further versions of Richie.

richie-3.0.1.dev2/docs/docker-development.md

@@ -0,0 +1,138 @@
+---
+id: docker-development
+title: Developing Richie with Docker
+sidebar_label: Docker development
+---
+
+Now that you have `Richie` up and running, you can start working with it.
+
+## Settings
+
+Settings are defined using [Django
+Configurations](https://django-configurations.readthedocs.io/en/stable/) for
+different environments:
+
+- `Development`: settings for development on developers' local environment,
+- `Test`: settings used to run our test suite,
+- `ContinousIntegration`: settings used on the continuous integration platform,
+- `Feature`: settings for deployment of each developers' feature branches,
+- `Staging`: settings for deployment to the staging environment,
+- `PreProduction`: settings for deployment to the pre-production environment,
+- `Production`: settings for deployment to the production environment.
+
+The `Development` environment is defined as the default environment.
+
+## Front-end tools
+
+If you intend to work on the front-end development of the CMS, we also have
+sweet candies for you! 🤓
+
+```bash
+# Start the Sass watcher
+$ make watch-sass
+
+# In a new terminal or session, start the TypeScript watcher
+$ make watch-ts
+```
+
+## Container control
+
+You can stop/start/restart a container:
+
+```bash
+    $ docker compose [stop|start|restart] [app|postgresql|mysql|elasticsearch]
+```
+
+or stop/start/restart all containers in one command:
+
+```bash
+    $ docker compose [stop|start|restart]
+```
+
+## Debugging
+
+You can easily see the latest logs for a container:
+
+```bash
+    $ docker compose logs [app|postgresql|mysql|elasticsearch]
+```
+
+Or follow the stream of logs:
+
+```bash
+    $ docker compose logs --follow [app|postgresql|mysql|elasticsearch]
+```
+
+If you need to debug a running container, you can open a Linux shell with the
+`docker compose exec` command (we use a sugar script here, see next section):
+
+```bash
+    $ bin/exec [app|postgresql|mysql|elasticsearch] bash
+```
+
+While developing on `Richie`, you will also need to run a `Django shell` and it
+has to be done in the `app` container (we use a sugar script here, see next
+section):
+
+```bash
+    $ bin/run app python sandbox/manage.py shell
+```
+
+## Using sugar scripts
+
+While developing using Docker, you will fall into permission issues if you mount
+the code directory as a volume in the container. Indeed, the Docker engine will,
+by default, run the containers using the `root` user. Any file created or
+updated by the app container on your host, as a result of the volume mounts,
+will be owned by the local root user. One way to solve this is to use the
+`--user="$(id -u)"` flag when calling the `docker compose run` or
+`docker compose exec` commands. By using the user flag trick, the running
+container user ID will match your local user ID. But, as it's repetitive and
+error-prone, we provide shortcuts that we call our "sugar scripts":
+
+- `bin/run`: is a shortcut for `docker compose run --rm --user="$(id -u)"`
+- `bin/exec`: is a shortcut for `docker compose exec --user="$(id -u)"`
+- `bin/pylint`: runs `pylint` in the `app` service using the test docker compose
+  file
+- `bin/pytest`: runs `pytest` in the `app` service using the test docker compose
+  file
+
+## Cleanup
+
+If you work on the Docker configuration and make repeated modifications,
+remember to periodically clean the unused docker images and containers by
+running:
+
+```bash
+    $ docker image prune
+    $ docker container prune
+```
+
+## Troubleshooting
+
+### ElasticSearch service is always down
+
+If your `elasticsearch` container fails at booting, checkout the logs via:
+
+```bash
+$ docker compose logs elasticsearch
+```
+
+You may see entries similar to:
+
+```
+[1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
+```
+
+In this case, increase virtual memory as follows (UNIX systems):
+
+```
+$ sudo sysctl -w vm/max_map_count=262144
+```
+
+This fix will apply to your current session. To make it permanent on your system, edit the
+`/etc/sysctl.conf` file and add the following line:
+
+```
+vm.max_map_count=262144
+```

richie-3.0.1.dev2/docs/installation.md

@@ -0,0 +1,104 @@
+---
+id: installation
+title: Installing Richie for development
+sidebar_label: Installation
+---
+
+`Richie` is a **container-native application** but can also be installed
+[on your machine](native-installation.md).
+
+For development, the project is defined using a
+[docker-compose file](../docker-compose.yml) and consists of:
+
+- 3 running services:
+    - **database**: `postgresql` or `mysql` at your preference,
+    - **elasticsearch**: the search engine,
+    - **app**: the actual `DjangoCMS` project with all our application code.
+
+- 2 containers for building purposes:
+
+    - **node**: used for front-end related tasks, _i.e._ transpiling
+    `TypeScript` sources, bundling them into a JS package, and building the
+    CSS files from Sass sources,
+    - **crowdin**: used to upload and retrieve i18n files to and from the
+    [Crowding](https://crowdin.com/) service that we use to crowd source
+    translations,
+
+At "France Université Numérique", we deploy our applications on `Kubernetes`
+using [`Arnold`](https://github.com/openfun/arnold).
+
+## Docker
+
+First, make sure you have a recent version of Docker and
+[Docker Compose](https://docs.docker.com/compose/install) installed on your
+laptop:
+
+```bash
+$ docker -v
+  Docker version 26.0.0, build 2ae903e
+
+$ docker compose --version
+  Docker Compose version v2.25.0
+```
+
+⚠️ You may need to run the following commands with `sudo` but this can be
+avoided by assigning your user to the `docker` group.
+
+### Project bootstrap
+
+The easiest way to start working on the project is to use our `Makefile`:
+
+```bash
+    $ make bootstrap
+```
+
+This command builds the `app` container, installs front-end and back-end
+dependencies, builds the front-end application and styles, and performs
+database migrations. It's a good idea to use this command each time you are
+pulling code from the project repository to avoid dependency-related or
+migration-related issues.
+
+Now that your `Docker` services are ready to be used, start the full CMS by
+running:
+
+```bash
+    $ make run
+```
+
+### Adding content
+
+Once the CMS is up and running, you can create a superuser account:
+
+```bash
+    $ make superuser
+```
+
+You can create a basic demo site by running:
+
+```bash
+    $ make demo-site
+```
+
+Note that if you don't create the demo site and start from a blank CMS, you
+will get some errors requesting you to create some required root pages. So it
+is easier as a first approach to test the CMS with the demo site.
+
+You should be able to view the site at [localhost:8070](http://localhost:8070)
+
+## Connecting Richie to an LMS
+
+It is possible to use Richie as a catalogue aggregating courses from one or
+more LMS without any specific connection. In this case, each course run in
+the catalogue points to a course on the LMS, and the LMS points back to the
+catalogue to browse courses.
+
+This approach is used for example on https://www.fun-campus.fr or
+https://catalogue.edulib.org.
+
+For a seamless user experience, it is possible to connect a Richie instance
+to an OpenEdX instance (or some other LMS like Moodle at the cost of minor
+adaptations), in several ways that we explain in the
+[LMS connection guide](lms-connection).
+
+This approach is used for example on https://www.fun-mooc.fr or
+https://www.nau.edu.pt.

richie-3.0.1.dev2/docs/lms-connection.md

@@ -0,0 +1,92 @@
+---
+id: lms-connection
+title: Connecting Richie with one or more LMS
+sidebar_label: LMS connection
+---
+
+## Connecting Richie to an LMS
+
+Richie can be connected to an LMS in several ways, ranging from SSO to a fully integrated
+seamless experience.
+
+As of today, each approach has been implemented for OpenEdX but the same could be done for
+other LMSes like Moodle, at the cost of minor adaptations.
+
+
+### 1. Displaying connection status
+
+OpenEdX can be configured to allow CORS requests. Doing so allows Richie to retrieve a user's
+connection status from OpenEdx and display the user's profile information directly on the Richie
+site: username, dashboard url, etc.
+
+In this approach, a user visiting your Richie site and trying to signup or login, is sent to the
+OpenEdX site for authentication and is redirected back to the Richie site upon successful login.
+
+You can see this in action on https://www.fun-mooc.fr.
+
+We provide detailed instructions on
+[how to configure displaying OpenEdX connection status in Richie](displaying-connection-status.md).
+
+
+### 2. Seamless enrollment
+
+Thanks to OpenEdX's enrollment API, it is possible to let users enroll on course runs without
+leaving Richie.
+
+You can see this in action on https://www.fun-mooc.fr.
+
+> This feature requires that Richie and OpenEdX be hosted on sibling domains i.e. domains that
+> are both subdomains of the same root domain, e.g. `richie.example.com` and `lms.example.com`.
+
+You should read our guide on [how to use OpenEdX as LMS backend for Richie](lms-backends).
+
+
+### 3. Synchronizing course runs details
+
+Course runs in Richie can be handled manually, filling all fields via the DjangoCMS front-end
+editing interface. But a better way to handle course runs is to synchronize them automatically
+from your LMS using the course run synchronization API.
+
+Please refer to our guide on [how to synchronize course runs between Richie and OpenEdx][sync]
+
+### 4. Joanie, the enrollment manager
+
+For more advanced use cases, we have started a new project called [Joanie] which acts as an
+enrollment manager for Richie.
+
+Authentication in Joanie is done via JWT Tokens for maximum flexibility and decoupling in
+identity management.
+
+The project is used in production by France Université Numérique and it handles :
+
+- paid enrollments / certification
+- micro-credentials
+- user dashboard
+- multi-LMS catalogs
+
+
+## Development
+
+For development purposes, the docker compose project provided on
+[Richie's code repository](https://github.com/openfun/richie) is pre-configured to connect
+with an OpenEdx instance started with
+[OpenEdx Docker](https://github.com/openfun/openedx-docker), which provides a ready-to-use
+docker compose stack of OpenEdx in several flavors. Head over to
+[OpenEdx Docker README](https://github.com/openfun/openedx-docker#readme) for instructions on how to bootstrap an OpenEdX instance.
+
+Now, start both the OpenEdX and Richie projects separately with `make run`.
+
+Richie should respond on `http://localhost:8070`, OpenEdx on `http://localhost:8073` and both
+apps should be able to communicate with each other via the network bridge defined in
+docker compose.
+
+If you want to activate [seamless enrollment](#2-seamless-enrollment) locally for development,
+you will need to set up TLS domains for both Richie and OpenEdX. To do this, head over to our
+guide on [setting-up TLS connections for Richie and OpenEdX](tls-connection).
+
+Otherwise, you can also use tunneling tools like [localtunnel](https://github.com/localtunnel/localtunnel)
+to expose your local server to the internet through https.
+
+
+[Joanie]: https://github.com/openfun/joanie
+[sync]: synchronizing-course-runs