Relaunch training.plone.org

[ksuess]

We discussed a relaunch (see requirements below) and agreed to

• switch all trainings from reST to MyST (superset of markdown)
• apply sphinx theme 'book'

we are: @ksuess, @spereverde, @stevepiercy, @pbauer
Contact us here or via Discord channel https://discord.gg/NES2f6dQ

As the conference with trainings is approaching, and trainers will contribute, this project is progressing well and should be terminated 2nd week of september.

Requirements

Must haves

• Search results show chapter, sub-training title, 'Plone Training'
  Example where training title is important to distinguish:
  "17. REST API – Volto Add-Ons – Plone Training"
  "23. REST API – Mastering Plone – Plone Training"
• Same for browser title: show training title
• Show always TOC (sticky). show current chapter. see [1]
• Code can be copied with a click
• Exercises with collapsed solutions
• Improve grammar and syntax, whether it is in Markdown, reStructuredText, Denglish or English.
• Keep presentation mode for a subset of text for presentation

Nice to haves

• to be discussed: markdown instead of rst for easier preview in code editor
• Overview pages for stories that cover multiple chapters that are connected via a story / general use case. Overview pages can have text with an intro and list of chapters plus a graphical navigation map.
  This navigation map shows where to start, where to follow up, which side info could be usefull. This map should be selectable and then stays visible for navigation.
  • Example: Roundtrip backend <-> frontend where you need to define restapi endpoints to fetch data and display in frontend. And you need maybe vocabularies and and and.
• Manually edited glossary. Manually editable references to glossary terms.
• Show tooltips in text for glossary terms.
• Refine search results by training

to be discussed

• we stay with backticks
• skip translations

Next steps

Milestone: https://github.com/plone/training/milestone/10

• Document process to convert files from from reST to MyST. Myst rst2myst conversion process #511. @stevepiercy
• Fix syntax issues, merge all individual trainings' conf.py, about/index.rst, about/glossary.rst, Makefile, LICENSE into a single file at the root level. These prevent a clean conversion using rst2myst and a clean build with make html. Myst syntax fixes #512. @stevepiercy
• stay with backticks @stevepiercy
• Convert all files from reST to MyST. Convert all files from reST to MyST #515. DO NOT MERGE. @stevepiercy
• Apply sphinxbook theme with fixes in docs: Apply theme "book" #516. This PR will be merged to Convert all files from reST to MyST #515. @ksuess
• Enhance search with training titles and filter by training Add training titles to search results. Add filter to search. #518. @ksuess
• STOP! Review open PR Convert all files from reST to MyST #515, and get blessing from @pbauer before merging Convert all files from reST to MyST #515.
  • What happens if the build process fails? @ericof created the GitHub Actions.
• Post-merge of Convert all files from reST to MyST #515 cleanup: removal of rst2myst: @stevepiercy
  • In conf.py remove rst2myst/training/** from exclude_patterns.
  • Delete the directory rst2myst.
  • Uninstall rst-to-myst: pip uninstall "rst-to-myst[sphinx]"
• Move trainings to docs/ @stevepiercy
• Delete translations. We use Google Translate now. @stevepiercy
• "guides for authors", "setup for trainers": move to /docs. Add info material for authors and trainers and add navigation entries #524 . @ksuess
• Rename master branch to main @stevepiercy To update your local clone:
  • git branch -m master main
  • git fetch origin
  • git branch -u origin/main main
  • git remote set-head origin -a
• English language fixes, grammar, spelling. @stevepiercy
• More info for authors and trainers ¹

Footnotes

1. Further valuable info for authors and trainers to be included:

   • some more info about code snippets: https://github.com/plone/training/pull/513#issuecomment-912169849
   • info about linkcheck
   • authors please check warnings before merging
   ↩

[stevepiercy]

Must haves

I use the theme by the Executable Book Project, Sphinx Book Theme, which is built on pydata_sphinx_theme. I agree with the list of "must haves", and there may be more.

I added a few customizations to the theme, which are trivial to implement. I changed the color of inline literals from hot pink to dark green with light grey, and improved enumerated lists to have better numbering when nested, i.e., 1, a, i, A.

Here's their toolset.

• to be discussed: markdown instead of rst for easier preview in code editor

MyST allows people to write Markdown which gets converted to reStructuredText then rendered to the desired output format. We can have the best of both Markdown and reST.

A couple of other nifty extensions.

• https://sphinx-panels.readthedocs.io/en/latest/
• https://sphinx-tabs.readthedocs.io/en/latest/

[ksuess]

We are inspired, @stevepiercy !
https://sphinx-book-theme.readthedocs.io/en/latest/ looks great and has a lot of features that I think are important to add to https://training.plone.org/ .
Another option is https://pydata-sphinx-theme.readthedocs.io/en/latest/ that Philip suggested and, before diving into Sphinx sphere, it seems that Sphinx, not the theme, is a great base with valuable addons / extensions.

What I would like to explore is the maybe plus of sphinx-book-theme of the jupyter notebook thing i'am curious about. https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html I'll read on…

Your reminder that we do not have to restrict on markdown or reStructuredTest seems to be important for attracting more contributors. Well, I think it's not a thing to learn the other markup language. A magic accepting both is welcome.

A retreat thing to think about is:
Overview pages for stories that cover multiple chapters that are connected via a story / general use case is a helping hand that I would like to see.

I am https://dict.leo.org/englisch-deutsch/gespannt and https://dict.leo.org/englisch-deutsch/neugierig to continue with the relaunch.

Didn't we speek about a maybe relaunch sometimes?

[ksuess]

@pbauer , @plone/training-team please add your must haves and nice to haves!

[ksuess]

@pbauer, please invite and convince @stevepiercy to join us after summer retreat on 04.08.2021 15:00 MESZ or propose an alternative date for moths.

[stevepiercy]

@ksuess @pbauer I would be happy to join later in the day, or at least work asynchronously. 1500 MESZ == 0600 PDT.

[stevepiercy]

https://sphinx-book-theme.readthedocs.io/en/latest/ looks great and has a lot of features that I think are important to add to https://training.plone.org/ .
Another option is https://pydata-sphinx-theme.readthedocs.io/en/latest/ that Philip suggested and, before diving into Sphinx sphere, it seems that Sphinx, not the theme, is a great base with valuable addons / extensions.

Sphinx Book theme is based on PyData theme, so you get all of its features and a few more (as well as more bugs, such as that issue with panels).

What I would like to explore is the maybe plus of sphinx-book-theme of the jupyter notebook thing i'am curious about. https://sphinx-book-theme.readthedocs.io/en/latest/notebooks.html I'll read on…

I don't know how useful notebooks would be for Plone or Volto, but it would be worth exploring. I think that we can have Docker containers that we can launch in Binder. On that Sphinx Book page, there is a rocket icon in the upper right, and has two options to launch the notebook.

Your reminder that we do not have to restrict on markdown or reStructuredTest seems to be important for attracting more contributors. Well, I think it's not a thing to learn the other markup language. A magic accepting both is welcome.

Indeed. I also envision two roles for docs contributors, Authors and Editors. Authors create content, Editors refine content and support Authors. I am not much of an Author, but I definitely can help improve grammar and syntax, whether it is in Markdown, reStructuredText, or English.

[spereverde]

fyi
#507 (comment) - POC with myst ready

[ksuess]

I am excited that this project has some drive now. So how to nourish this energy? I have a great interest in a relaunch and I want to contribute as much as possible. Unfortunatly I planned to be offline the next three weeks. And @spereverde who already put effort in this is afterwards not available. So I propose that we do what we think is important to do. We document the tasks in the above list of requirements (must haves, nice to haves) and also in the repo itself (folder '_doc').

Do you @spereverde, @stevepiercy, @pbauer can spare some minutes to review the work 25. August 0900 PDT (1800 MESZ)? That would be great!

[stevepiercy]

I would like to see @spereverde's proof of concept on a new and separate branch and PR. That way we can merge it into any other branch when it is ready.

25 August 0900 PDT (1800 MESZ) is on my calendar.

Plone folks are using Discord now for chat, voice, and video. I have Owner permission. I can create a specific channel for this project. Do we have a need to use Discord for this project? I imagine it would be useful for sharing stuff we do not want out in the public, like when I'm away on vacation so that burglars can break into my home.

[ksuess]

Yes, you are right these two can be separate PRs. For a preview we can combine locally.

Would you create a channel?

[stevepiercy]

Discord channel created: https://discord.gg/d9dZcA4Ezw

Milestone created: https://github.com/plone/training/milestone/10

Please feel free to add issues and pull requests to the milestone.

[spereverde]

PR #508 for myst added to https://github.com/plone/training/milestone/10

[stevepiercy]

I modified and added a couple more items to the checklist above.

• Document process to convert files from from reST to MyST. Myst rst2myst conversion process Myst rst2myst conversion process #511. @stevepiercy
• Fix syntax issues, merge all individual trainings' conf.py, about/index.rst, about/glossary.rst, Makefile, LICENSE into a single file at the root level. These prevent a clean conversion using rst2myst and a clean build with make html. Myst syntax fixes Myst syntax fixes #512. @stevepiercy
• Do we move trainings into a sub-folder? @stevepiercy says YES! See https://discord.com/channels/786421998426521600/862642144401031188/882356355283963914
• Where do we keep non-training documentation, such as tips for MyST syntax, how to build the docs, and so on?
• Why use colons for codefence over backticks?

For us, I recommend that you rebase your current working branches on #512 myst-syntax-fixes, which in turn is based on #511 myst-rst2myst-conversion-process.

[ksuess]

It is important not to touch the docs without taking #516 into account as there are already theme specific changes to markdown files (converted by #515), @stevepiercy, thanks!

[stevepiercy]

I think we can close this issue, as we've completed most items. I think that the only things that need English touch-up will be those trainings that will be for 2021. I can review those PRs as they come in, and hopefully no one pushes to main.

Any remaining items should have their own issue to track them going forward.

[ksuess]

huh, this would probably need a friendly reminder to teachers: "Please work with PR. If you are interested, Steve is so kind to help with a English touch-up."

[stevepiercy]

I posted https://community.plone.org/t/training-documentation-overhaul/14326 and to Discord already.

I would like authors and trainers of PloneConf 2021 trainings to assign reviewers on all PRs when they are ready for English review. I should not be the only reviewer. Some trainers might not need to revise their docs. We (@pbauer @ksuess @spereverde and maybe others? ) all need to encourage that practice.

[stevepiercy]

I see only three unchecked boxes remaining in this issue.

• Overview pages for stories that cover multiple chapters that are connected via a story / general use case.
  Overview pages can have text with an intro and list of chapters plus a graphical navigation map.
  This navigation map shows where to start, where to follow up, which side info could be usefull. This map should be selectable and then stays visible for navigation.
  • Example: Roundtrip backend <-> frontend where you need to define restapi endpoints to fetch data and display in frontend. And you need maybe vocabularies and and and.
• Show tooltips in text for glossary terms.

I created a separate issue to track the last item. #540

I need to see an example of the first and second items.

I would suggest closing this issue, and elaborating on the first and second items in a new separate issue.

[spereverde]

Seems like good idea to me to close this issue and follow up the others in separate issues, the most important work is done, but @ksuess and @pbauer should agree

[ksuess]

Released.
Overview of tasks done: https://community.plone.org/t/training-documentation-overhaul/14326
More enhancements to come: https://github.com/plone/training/milestone/10
Authors my have look at https://training.plone.org/5/contributing/authors.html#american-english-spelling-grammar-and-syntax and ask for a review.