Merge branch 'main' into nuclia_widget

.github/workflows/rtd-pr-preview.yml

@@ -18,5 +18,5 @@ jobs:
     steps:
       - uses: readthedocs/actions/preview@v1
         with:
-          project-slug: "plone6"
+          project-slug: "plone-training"
           single-version: "true"

.readthedocs.yaml

@@ -18,7 +18,7 @@ build:
     # If there are no changes (git diff exits with 0) we force the command to return with 183.
     # This is a special exit code on Read the Docs that will cancel the build immediately.
     - |
-      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements.txt;
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .github/workflows/rtd-pr-preview.yml .readthedocs.yaml requirements.txt;
       then
         exit 183;
       fi

Makefile

@@ -29,13 +29,9 @@ clean:  ## Clean build directory
 	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/*
 
 .PHONY: distclean
-distclean:  ## Clean docs build directory and Python virtual environment, then install requirements
+distclean:  ## Clean docs build directory and Python virtual environment
+	rm -rf venv
 	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
-	python3 -m venv venv --clear
-	venv/bin/python -m pip install --upgrade pip
-	venv/bin/pip install -r requirements.txt
-	@echo
-	@echo "Installation of requirements completed."
 
 venv/bin/python:  ## Set up training: Install requirements
 	python3 -m venv venv

docs/conf.py

@@ -132,7 +132,19 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = [
+    "mastering-plone-5/timing.md",
+    "theming/diazo-notes.md",
+    "voltohandson/blocksdownload.md",
+    "voltohandson/blocksedit.md",
+    "voltohandson/contenttypesviews.md",
+    "voltohandson/contenttypesviews.md",
+    "voltohandson/contenttypeview.md",
+    "voltohandson/eventlistingtemplate.md",
+    "voltohandson/highlight.md",
+    "voltohandson/highlightsblock.md",
+    "voltohandson/introtovolto.md",
+]
 
 
 # -- Options for HTML output -------------------------------------------------

docs/contributing/setup-build.md

@@ -142,13 +142,6 @@ make vale
 
 See the output on the console for suggestions.
 
-You can also pass options to vale in the `VALEOPTS` environment variable.
-In the following example, vale will not return a non-zero exit code when there are errors and will display warnings or errors only, not suggestions.
-
-```shell
-make vale VALEOPTS="--no-exit --minAlertLevel='warning'"
-```
-
 
 ### `html_meta`
 
@@ -158,3 +151,29 @@ See {ref}`authors-html-meta-data-label` for more info.
 ```shell
 make html_meta
 ```
+
+
+## Overriding configuration options
+
+Both Sphinx and vale support overriding configuration options.
+The following examples serve as tips for spotting mistakes in your training.
+
+In Sphinx, you can use the `SPHINXOPTS` environment variable to set [configuration options](https://www.sphinx-doc.org/en/master/usage/configuration.html) of [`sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html).
+Syntax is in the following form.
+
+```shell
+make SPHINXOPTS="OPTION VALUE" BUILDER
+```
+
+The following example shows how to clean then build a live HTML preview of the trainings while suppressing syntax highlighting failures.
+
+```shell
+make SPHINXOPTS="-D suppress_warnings=['misc.highlighting_failure']" clean livehtml
+```
+
+You can also pass options to vale in the `VALEOPTS` environment variable.
+In the following example, vale will not return a non-zero exit code when there are errors and will display warnings or errors only, not suggestions.
+
+```shell
+make vale VALEOPTS="--no-exit --minAlertLevel='warning'"
+```

docs/effective-volto/addons.md

@@ -10,12 +10,10 @@ myst:
 # Add-ons
 
 ```{toctree}
----
-caption: Add-ons
-name: toc-effective-volto-addons
-maxdepth: 2
-numbered: true
----
+:caption: Add-ons
+:name: toc-effective-volto-addons
+:maxdepth: 2
+:numbered:
 
 addons/what-is-an-addon
 addons/bootstrap

docs/effective-volto/addons/use-repo-addon.md

@@ -123,17 +123,13 @@ you'll have to set your addon package as a "Yarn workspace". You do this by
 adding a `workspaces` key to the the `package.json` of your Volto project:
 
 ```json
-...
 "workspaces": ["src/addons/my-volto-addon"],
-...
 ```
 
 It is common practice to use a star glob pattern for the workspaces:
 
 ```json
-...
 "workspaces": ["src/addons/*"],
-...
 ```
 
 If you do this, make sure to always cleanup the `src/addons` folder whenever

docs/effective-volto/architecture.md

@@ -12,12 +12,10 @@ myst:
 Intro
 
 ```{toctree}
----
-caption: Architecture
-name: toc-effective-volto-architecture
-maxdepth: 2
-numbered: true
----
+:caption: Architecture
+:name: toc-effective-volto-architecture
+:maxdepth: 2
+:numbered:
 
 architecture/client-ssr
 architecture/razzle

docs/effective-volto/architecture/CORS.md

@@ -42,7 +42,7 @@ However, the recommendation is that you forget that CORS exists and "play well"
 These scenarios are:
 
 - Our frontend and backend are in the same domain (thus, avoiding the cross-domain issue), or
-- Using the internal proxy provided by Volto's NodeJS SSR server
+- Using the internal proxy provided by Volto's Node.js SSR server
 
 During development, the last one is the one you are going to use.
 The default backend will live in `http://localhost:8080/Plone` and the frontend in `http://localhost:3000`. If your Plone site is not named `Plone` (so its url is something like `http://localhost:8080/mysite`, you can still use Seamless mode by creating a file called `.env.development` in the Volto project root with something like this:

docs/effective-volto/architecture/bootstrap-volto.md

@@ -14,12 +14,12 @@ For the most up-to-date information on how to get started with Volto, the offici
 A copy of this information is placed here, with the caveat that it may be out of date by the time you're reading this.
 ```
 
-## Install nvm (NodeJS version manager)
+## Install nvm (Node.js version manager)
 
 If you have a working Node JavaScript development already set up on your machine or you prefer
 another management tool to install/maintain node this step is not needed. If you have less
 experience with setting up JavaScript, it's a good idea to integrate nvm for development, as
-it provides easy access to any NodeJS released version.
+it provides easy access to any Node.js released version.
 
 1.  Open a terminal console and type:
 
@@ -42,7 +42,7 @@ it provides easy access to any NodeJS released version.
     nvm version
     ```
 
-4.  Install any active LTS version of NodeJS (https://github.com/nodejs/release#release-schedule):
+4.  Install any active LTS version of Node.js (https://github.com/nodejs/release#release-schedule):
 
     ```bash
     nvm install 18

docs/effective-volto/backend.md

@@ -12,12 +12,10 @@ myst:
 Intro
 
 ```{toctree}
----
-caption: Backend
-name: toc-effective-volto-backend
-maxdepth: 2
-numbered: true
----
+:caption: Backend
+:name: toc-effective-volto-backend
+:maxdepth: 2
+:numbered:
 
 backend/plone-restapi-endpoints
 backend/writing-endpoint

docs/effective-volto/deployment.md

@@ -10,12 +10,10 @@ myst:
 # Deployment
 
 ```{toctree}
----
-caption: Deployment
-name: toc-effective-volto-deployment
-maxdepth: 2
-numbered: true
----
+:caption: Deployment
+:name: toc-effective-volto-deployment
+:maxdepth: 2
+:numbered:
 
 deployment/seamlessmode
 deployment/simple

docs/effective-volto/development.md

@@ -11,12 +11,10 @@ myst:
 
 
 ```{toctree}
----
-caption: Development tools
-name: toc-effective-volto-development
-maxdepth: 2
-numbered: true
----
+:caption: Development tools
+:name: toc-effective-volto-development
+:maxdepth: 2
+:numbered:
 
 development/setup
 development/environmentvariables

docs/effective-volto/getting-started.md

@@ -17,12 +17,10 @@ So, we will be bootstrapping a Full Plone 6 project in order to follow the train
 
 
 ```{toctree}
----
-caption: Getting Started
-name: toc-effective-volto-getting-started
-maxdepth: 2
-numbered: true
----
+:caption: Getting Started
+:name: toc-effective-volto-getting-started
+:maxdepth: 2
+:numbered:
 
 getting-started/project
 getting-started/add-on

docs/effective-volto/index.md

@@ -22,11 +22,9 @@ Tips and tricks will be also covered, providing a good amount of insights for th
 This training is intended for an intermediate audience that already has some contact with Volto and tried it out, or has a decent amount of experience with it. Even experienced Volto developers will find this training useful, as less known areas of Volto are exposed.
 
 ```{toctree}
----
-caption: Effective Volto
-name: toc-effective-volto
-maxdepth: 3
----
+:caption: Effective Volto
+:name: toc-effective-volto
+:maxdepth: 3
 
 about_effective_volto
 getting-started

docs/effective-volto/testing.md

@@ -10,12 +10,10 @@ myst:
 # Testing
 
 ```{toctree}
----
-caption: Testing
-name: toc-effective-volto-testing
-maxdepth: 2
-numbered: true
----
+:caption: Testing
+:name: toc-effective-volto-testing
+:maxdepth: 2
+:numbered:
 
 testing/acceptance
 testing/jest

docs/index.md

@@ -18,9 +18,9 @@ A collection of trainings developed and created by the Plone community.
 
 mastering-plone/index
 mastering-plone-5/index
+volto-customization/index
 voltohandson/index
 voltoaddons/index
-volto_customization/index
 effective-volto/index
 testing/index
 theming/index
@@ -44,74 +44,76 @@ teaching/index
 
 {ref}`mastering-plone-label`
 
-: Best practices of Plone development, backend and frontend.
+:   Best practices of Plone development for both the backend and frontend.
 
 {ref}`mastering-plone5-label`
 
-: *Mastering Plone 5 development training* is the predecessor of the Plone 6 version. It includes also *Plone Classic* topics like viewlets, views, portlets, etc..
+:   Mastering Plone 5 development training is the predecessor of the Plone 6 version.
+    It includes also Plone Classic UI topics including viewlets, views, portlets, and other customizations.
 
 {doc}`testing/index`
 
-: Best practices for testing Plone add-ons.
+:   Best practices for testing Plone add-ons.
 
 
 ## Volto, React, and Javascript
 
-{doc}`voltohandson/index`
+{doc}`volto-customization/index`
 
-: Learn how to quickly bootstrap and customize a Volto project
+:   Are you new to JavaScript development and eager to explore the world of Volto customization?
+    Unlock the power of Volto, the modern React-based CMS framework for Plone, by joining our comprehensive half-day training designed specifically for JavaScript beginners.
 
-{doc}`voltoaddons/index`
+{doc}`voltohandson/index`
 
-: Build custom Volto add-ons, explore more advanced Volto topics.
+:   Learn how to quickly bootstrap and customize a Volto project
 
-{doc}`volto_customization/index`
+{doc}`voltoaddons/index`
 
-: Are you new to JavaScript development and eager to explore the world of Volto customization? Unlock the power of Volto, the modern React-based CMS framework for Plone, by joining our comprehensive half day training designed specifically for JavaScript beginners.
+:   Build custom Volto add-ons, explore more advanced Volto topics.
 
 {doc}`effective-volto/index`
 
-: Learn proven practices of Plone frontend development.
-  The training covers essential concepts, as well as good practices and notions of how Volto works under the hood.
-  Tips and tricks are also covered, providing a good amount of insights for those who want to learn more beyond the Volto basics.
-  Training for intermediate/advanced developers.
+:   Learn proven practices of Plone frontend development.
+    The training covers essential concepts, as well as good practices and notions of how Volto works under the hood.
+    Tips and tricks are also covered, providing a good amount of insights for those who want to learn more beyond the Volto basics.
+    Training for intermediate/advanced developers.
 
 [Use, Integrate and develop Patterns for Plone 6 Classic](https://patternslib.github.io/patternslib-training)
 
-: Use, create and integrate JavaScript functionality based on [Patternslib](https://patternslib.com/) into Plone 6.
+:   Use, create and integrate JavaScript functionality based on [Patternslib](https://patternslib.com/) into Plone 6.
 
 
 ## Theming
 
 {doc}`theming/index`
 
-: Theming Plone 6 Classic UI
+:   Theming Plone 6 Classic UI
 
 
 ## Deployment
 
 {doc}`plone-deployment/index`
 
-: Deploying Plone 6 for production purposes with Ansible and Docker
+:   Deploying Plone 6 for production purposes with Ansible and Docker
 
 
 ## Other
 
 {doc}`workflow/index`
 
-: How to create and make optimum use of custom Plone workflows
+:   How to create and make optimum use of custom Plone workflows
 
 {doc}`migrations/index`
 
-: Upgrading and migrating Plone sites using `collective.exportimport` and other methods.
+:   Upgrading and migrating Plone sites using `collective.exportimport` and other methods.
 
 {doc}`contributing/index`
 
-: All about contributing to documentation
+:   All about contributing to documentation
 
 {doc}`teaching/index`
 
-: How To Give Technical Trainings
+:   How To Give Technical Trainings
 
 
 ## Archived trainings

docs/mastering-plone-5/add-ons.md

@@ -107,7 +107,7 @@ Once you found an add-on you like you should ask the community if you made a goo
 - Message Board: <https://community.plone.org>
 - Chat: <https://plone.org/support/chat>
 
-There is also a talk that discusses in depth how to find the right add-on: <https://www.youtube.com/watch?v=Sc6NkqaSjqw>
+There is also a talk that discusses in depth how to find the right add-on: <https://www.youtube-nocookie.com/embed/Sc6NkqaSjqw?privacy_mode=1>
 
 (plone5-add-ons-installing-label)=