Training documentation overhaul

We just merged a boatload of improvements to the Training documentation. These changes may be of interest to authors, trainers, and readers.

  • Conversion of reStructuredText source files to MyST, allowing authors to write documentation in either Markdown or reStructuredText. The source files now all have .md extensions.
  • sphinx-book-theme is the new theme with lots of usability, readability, and mobile first goodness.
  • Search now allows searching all trainings or within a specific training: Search — Plone Training 2021 documentation
  • Improved navigation: site navigation on the left, local page content navigation (if it exists) on the right.
  • Fullscreen mode.
  • Links to GitHub to visit the source code or create a new issue.
  • Reorganized Contributing section that target Authors, Trainers, and Readers: Contributing to Plone Trainings Documentation — Plone Training 2021 documentation
  • Improved Teaching guide for Trainers: Teaching — Plone Training 2021 documentation
  • Moved all training related files to a sub-directory /docs to make it clear what is and is not Training docs.
  • Reinstated linkcheck and spellcheck to validate links and spelling. Contributors may use make linkcheck or make spellcheck to run the checkers. The checkers also run on every pull request and pushed commit.
  • Fixed hundreds of dead links and misspelled words through checkers. Please keep these up to date.
  • Unified all Glossary, conf.py, and related Sphinx files into single files at the source root directory docs/. Please use and update Glossary terms.
  • Resolved about 30 open issues and pull requests in the Training repository. Please contribute fixes, close obsolete issues, and update still valid issues.

Please feel free to join us on the Discord channel #training-docs to discuss further improvements to the Trainings.

Thank you!

7 Likes

Thanks to @ksuess, @stevepiercy and @spereverde for making all this happen!

Also: For Plone Conference 2021 a couple of new trainings will be published on trainings.plone.org. :tada:

1 Like

Plone Foundation Code of Conduct