Merge branch 'main' into vlt-training

.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

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/mastering-plone-5/index.md

@@ -21,12 +21,10 @@ Mastering Plone is intended as a week-long training for people who are new to Pl
 At conferences a shortened 2-day version of the advanced training with a slightly modified order is held.
 
 ```{toctree}
----
-caption: Mastering Plone 5 Development
-name: toc-mastering5
-maxdepth: 3
-numbered: 2
----
+:caption: Mastering Plone 5 Development
+:name: toc-mastering5
+:maxdepth: 3
+:numbered: 2
 
 about_mastering
 intro

docs/mastering-plone-5/instructions_plone5/index.md

@@ -157,7 +157,7 @@ If you point your browser at <http://localhost:8080> you see that Plone is runni
 A running plone instance.
 ```
 
-There is no Plone site yet - we will create one in {doc}`/mastering-plone-5/instructions_plone5/features`.
+There is no Plone site yet - we will create one in {doc}`/mastering-plone-5/features`.
 
 Now you have a working Plone site up and running and can continue with the next chapter.
 

docs/mastering-plone-5/instructions_plone5/what_vagrant_does.md

@@ -5,6 +5,7 @@ myst:
     "property=og:description": ""
     "property=og:title": ""
     "keywords": ""
+orphan:
 ---
 
 # What Vagrant is and does

docs/mastering-plone/index.md

@@ -31,12 +31,10 @@ For Plone Classic see training {doc}`/theming/index`, training {doc}`/mastering-
 ```
 
 ```{toctree}
----
-caption: Mastering Plone 6 Development
-name: toc-mastering
-maxdepth: 3
-numbered: 2
----
+:caption: Mastering Plone 6 Development
+:name: toc-mastering
+:maxdepth: 3
+:numbered: 2
 
 about_mastering
 intro

docs/mastering-plone/volto_testing.md

@@ -103,7 +103,7 @@ For example you see that the heading is the talk title with preceding type of ta
 
 {file}`packages/volto-ploneconf/src/components/Views/__snapshots__/Talk.test.js.snap`
 
-```html
+```js
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`renders a talk view component with only required props 1`] = `

docs/plone-deployment/project-edit.md

@@ -28,11 +28,11 @@ Edit {file}`frontend/src/addons/volto-ploneconf2023/package.json` and append `@p
 
 ```json
 "addons": [
-  ...,
+  "...more add-ons",
   "@plonegovbr/volto-code-block"
 ],
 "dependencies": {
-  ...,
+  "...more dependencies": "*",
   "@plonegovbr/volto-code-block": "*"
 }
 ```

docs/plone-deployment/server-setup.md

@@ -29,7 +29,7 @@ cp .env_dist .env
 
 Customize the {file}`.env` file to match your specific deployment environment. Here’s an example configuration:
 
-```plaintext
+```shell
 DEPLOY_ENV=prod
 DEPLOY_HOST=ploneconf2023-<user>.tangrama.com.br
 DEPLOY_PORT=22

docs/teaching/after.md

@@ -1,10 +1,10 @@
 ---
 myst:
   html_meta:
-    "description": ""
-    "property=og:description": ""
-    "property=og:title": ""
-    "keywords": ""
+    "description": "After the training: Aftercare, keep in touch, learn, improve"
+    "property=og:description": "After the training: Aftercare, keep in touch, learn, improve"
+    "property=og:title": "After the training: Aftercare, keep in touch, learn, improve"
+    "keywords": "Plone, Training, aftercare, keep in touch, learn, improve"
 ---
 
 (trainthetrainers-after-the-training-label)=
@@ -17,8 +17,8 @@ This chapter is a work in progress
 
 You're done with your training. Or so you think:
 
-> - Aftercare
-> - Keep in Touch
-> - Evaluate
-> - Improve training material
-> - Get quotes
+- Aftercare
+- Keep in Touch
+- Evaluate
+- Improve training material
+- Get quotes

docs/teaching/before.md

@@ -1,15 +1,15 @@
 ---
 myst:
   html_meta:
-    "description": ""
-    "property=og:description": ""
-    "property=og:title": ""
-    "keywords": ""
+    "description": "Before the training: Create material, invite trainees, preparation"
+    "property=og:description": "Before the training: Create material, invite trainees, preparation"
+    "property=og:title": "Before the training: Create material, invite trainees, preparation"
+    "keywords": "Plone, Training, material, invite, trainees, preparation"
 ---
 
 (trainthetrainers-before-the-training-label)=
 
-# Before the training: Create  material, invite trainees, preparation
+# Before the training: Create material, invite trainees, preparation
 
 ```{warning}
 This chapter is a first version.