From ca23ef88826a30e23858ff65f824059c90168050 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 10 Sep 2021 22:38:47 -0700 Subject: [PATCH 01/34] Add React to the glossary. The proper name is React, not ReactJS. --- docs/glossary.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/glossary.md b/docs/glossary.md index e12f7be07..3205aa3a6 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -136,7 +136,7 @@ Shadowing (Volto) By using this mechanism Volto enables customization (file overrides), similar to `z3c.jbot.` Razzle - A tool that simplifies SPA and SSR configuration for ReactJS projects. + A tool that simplifies SPA and SSR configuration for React projects. Webpack A tool that loads and bundles code and web resources using loaders. @@ -154,7 +154,7 @@ Express Volto uses it as its server. Server-Side Rendering (SSR) - When first loading any Plone page, users will get HTML markup that closely matches the final DOM structure of the react components used to render that page. + When first loading any Plone page, users will get HTML markup that closely matches the final DOM structure of the React components used to render that page. Single Page Application (SPA) A type of JavaScript application that aims to provide a better user experience by avoiding unnecessary reloading of the browser page, instead using AJAX to load backend information. @@ -205,4 +205,8 @@ hoisting (Yarn) By default JavaScript packages will directly include dependencies inside their local node_modules. By hoisting we're "lifting" these inner dependencies to the top level `node_modules` directory, and thus optimize the generated bundles. In case two dependencies have conflicting version dependencies of the same library, the hoisting will not be possible (for that conflicting dependency) and you'll see multiple instances of the same library in the bundle, or you'll see that the add-on receives its own `node_modules` folder. + +React + [React](https://reactjs.org/) is a JavaScript library for building user interfaces. + Volto, the frontend for Plone 6, uses React. ``` From 8d8727666386e184e7aaa0f420be231f7766827f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 11 Sep 2021 00:24:08 -0700 Subject: [PATCH 02/34] Fix GitHub navigation links --- docs/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 5f68491b5..55d13a4c1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -154,6 +154,8 @@ html_theme_options = { "repository_url": "https://github.com/plone/training", + "repository_branch": "main", + "path_to_docs": "docs", "use_repository_button": True, "use_issues_button": True, "use_edit_page_button": True, From af17893e7c6ff0b62023be404c20396b82dd7cf8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 11 Sep 2021 02:51:09 -0700 Subject: [PATCH 03/34] Expand Contributing to include Plone CLA/publishing permission, using GitHub, documentation quality, Plone code of conduct. Move content about contributing to contributing/index Add GitHub navigation image and information --- .../_static/github-navigation.png | Bin 0 -> 11221 bytes docs/contributing/index.md | 98 +++++++++++++++--- docs/contributing/setup-author.md | 86 +++++++++++++-- 3 files changed, 163 insertions(+), 21 deletions(-) create mode 100644 docs/contributing/_static/github-navigation.png diff --git a/docs/contributing/_static/github-navigation.png b/docs/contributing/_static/github-navigation.png new file mode 100644 index 0000000000000000000000000000000000000000..ef6f90d1c79b880291b47c07b57213385333f836 GIT binary patch literal 11221 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 MVsfI@!uo;#1Jp5IrvLx| literal 0 HcmV?d00001 diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 007bf6f87..8fde0e6b9 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,20 +1,81 @@ -# Contributing +# Contributing to Plone Trainings Documentation -## Contributing to Plone Trainings Documentation training.plone.org +This document describes how to contribute to the Plone Trainings Documentation. -You are welcome to contribute. +Contributions to the Plone Trainings documentation are welcome. -You see something that could be enhanced? -: On top of every page you see links to commit suggestions. +## Granting permission to publish -You are author -: You want to enhance existing chapters or even create a new training. -: Find some hints for authoring with -**markdown and Sphinx and the extra MyST options**: -{doc}`markup-syntax` -: Find instructions how to set up training documentation locally in {doc}`setup-author` +Before you contribute, you must give permission to publish your contribution according to the license we use. +You may give that permission in two ways. - Make sure you have filled out a [Contributor Agreement](https://plone.org/foundation/contributors-agreement). +- Sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement). + This method also covers contributions to Plone code. + It is a one-time only process. +- In every pull request or commit message, include the following statement. + + > I, [full name], agree to have this contribution published under Creative Commons 4.0 International License (CC BY 4.0), with attribution to the Plone Foundation. + +The Plone Trainings Documentation is licensed under the [Creative Commons Attribution 4.0 International License (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). +A copy of the license is included in the root of this repository. + + +## GitHub + +Contributions are managed through the [Training repository on GitHub](https://github.com/plone/training). + +First discuss whether you should perform any work. +Any method below is acceptable, but are listed in order of most likely to get a response. + +- [Search for open issues](https://github.com/plone/training/issues) and comment on them. +- [Create a new issue](https://github.com/plone/training/issues/new/choose). +- Discuss during conferences, trainings, and other Plone events. +- Ask on the [Plone Community Forum, Documentation topic](https://community.plone.org/c/documentation/13). +- Ask in the [Plone chat on Discord](https://discord.gg/zFY3EBbjaj). + +As a convenience, at the top right of every page, there is a GitHub navigation menu. +Tap, click, or hover over the GitHub Octocat icon for options. + +```{image} _static/github-navigation.png +:alt: GitHub navigation menu +``` + +You can use this menu to quickly navigate to the source repository, open an issue, or suggest an edit to the current document. +Of course, you can use whichever tools you like. + +Next edit files, commit your changes, push them to the remote repository, and submit a pull request to resolve the issue. + +Members who subscribe to the repository will receive a notification and review your request. + + +## Contribution quality requirements + +Although we perform automatic testing of the documentation build through GitHub Actions with every pull request, you can catch errors and warnings by building the documentation locally. +See [TBD] for instructions on how to set up and build the documentation. + +We strive for high quality documentation, setting the following minimum standards. + +- Markup syntax must be valid. + See [TBD] for details. +- Good English grammar, spelling, and syntax. + Any locale of English is fine. + + We understand that contributors might not be fluent in English. + Community members who are fluent in English are available to help. + + Certain spellings are enforced through `TBD`. + See [TBD] for details. +- All links must be valid. + This is enforced through `linkcheck`. + See [TBD] for details. +- The documentation must build successfully without warnings. + We may exempt this requirement for specific cases. + + +## Code of Conduct + +The Plone Foundation has published a [Code of Conduct](https://plone.org/foundation/materials/foundation-resolutions/code-of-conduct). +All contributors to the Plone Trainings Documentation follow the Code of Conduct. ```{toctree} @@ -24,6 +85,13 @@ maxdepth: 2 hidden: true --- -markup-syntax -setup-author -``` \ No newline at end of file +instructions +setup_author +``` + +Changes to pages: + +- index (general contributing) +- markup-syntax (rename of instructions) +- setup-build (part from setup_author) +- trainers (part from setup_author) diff --git a/docs/contributing/setup-author.md b/docs/contributing/setup-author.md index 278c3adcd..27599f8d6 100644 --- a/docs/contributing/setup-author.md +++ b/docs/contributing/setup-author.md @@ -1,8 +1,71 @@ -# Building the documentation locally +(about-use-label)= -If you want to contribute to the training documentation or teach with a local version of the training documentation, here are the steps to take for a local setup. +# Using the documentation for a training -## Dependencies and new build +Feel free to organize a training yourself. +Please be so kind to contribute any bug fixes or enhancements you made to the documentation for your training. + +## Complete Mode and compact Presentation Mode + +The training is rendered using Sphinx and builds in two flavors: + +default +: The verbose version used for the online documentation and for the trainer. +: Build it in Sphinx with `make html` or use the online version. + +presentation +: An abbreviated version used for the projector during a training. +: It should use more bullet points than verbose text. +: Build it in Sphinx with `make presentation`. + +:::{note} +By prefixing an indented block of text or code with `.. only:: presentation` you can control +that this block is used for the presentation version only. + +To hide a block from the presentation version use `.. only:: not presentation` + +Content without a prefix will be included in both versions. +::: + + +## Exercises and Solutions + +Collapsed solutions of exercises: + +````{admonition} Complete code of the component Sed posuere consectetur est at lobortis. +:class: toggle + +```{code-block} jsx +:linenos: +:emphasize-lines: 2,4 + +import React from 'react'; +import { defineMessages, injectIntl } from 'react-intl'; +import { v4 as uuid } from 'uuid'; +import { omit, without } from 'lodash'; +``` +```` + +Be aware of the nested directives! Increase back ticks! + + ````{admonition} Complete code of the component + :class: toggle + + ```{code-block} jsx + :linenos: + :emphasize-lines: 2,4 + + import React from 'react'; + import { defineMessages, injectIntl } from 'react-intl'; + import { v4 as uuid } from 'uuid'; + import { omit, without } from 'lodash'; + ``` + ```` + + +## Building the documentation locally + +### Dependencies and new build Please make sure that you have [Enchant](https://abiword.github.io/enchant/) installed. This is needed for spell-checking. @@ -129,6 +192,10 @@ zip -r ../_static/plone_training_config.zip * If you are a trainer there is a special mini training about giving technical trainings. These chapters don't contain any Plone specific advice. There's background, theory, check lists, and tips for anyone trying to teach technical subjects: {doc}`/teachers-training/index` +These chapters don't contain any Plone specific advice. +There's background, theory, check lists, and tips for anyone trying to teach technical subjects. + +{doc}`/teachers-training/index` (about-contribute-label)= @@ -138,11 +205,18 @@ Everyone is **very welcome** to contribute. Minor bug fixes can be pushed directly in the [repository](https://github.com/plone/training), bigger changes should be made as [pull-requests](https://github.com/plone/training/pulls/) and discussed previously in tickets. -Make sure you have filled out a [Contributor Agreement](https://plone.org/foundation/contributors-agreement). - - (about-licence-label)= ## License The Mastering Plone Training is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). + +Make sure you have filled out a [Contributor Agreement](https://plone.org/foundation/contributors-agreement). + +If you haven't filled out a Contributor Agreement, you can still contribute. +Contact the Documentation team, for instance via the [mailinglist](https://sourceforge.net/p/plone/mailman/plone-docs/) +or directly send a mail to + +Basically, all we need is your written confirmation that you are agreeing your contribution can be under Creative Commons. + +You can also add in a comment with your pull request "I, \, agree to have this published under Creative Commons 4.0 International BY". From 65737ea12ff4a0db12d0aabb83925aa688d93ad8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 11 Sep 2021 02:52:03 -0700 Subject: [PATCH 04/34] Add MyST and Markdown to Glossary --- docs/glossary.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index 3205aa3a6..83f6c6b0c 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -209,4 +209,10 @@ hoisting (Yarn) React [React](https://reactjs.org/) is a JavaScript library for building user interfaces. Volto, the frontend for Plone 6, uses React. + +MyST + [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/) is a rich and extensible flavor of Markdown, for authoring training documentation. + +Markdown + [Markdown](https://daringfireball.net/projects/markdown/) is a text-to-HTML conversion tool for web writers. ``` From 22709b6d90859f08a91b47a8770149e24926b571 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 02:47:33 -0700 Subject: [PATCH 05/34] Update link to contributing. --- .github/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 34ffb9bc2..d2e79a965 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1 +1 @@ -See our [contributing guidelines](https://training.plone.org/about/). \ No newline at end of file +See our [contributing guidelines](https://training.plone.org/5/contributing/index.html). \ No newline at end of file From 872d0b592c74480df00a043ccf0633142ccf8d59 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 02:49:09 -0700 Subject: [PATCH 06/34] The guide is for any contributor, not just authors Fix proper noun case --- docs/contributing/markup-syntax.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing/markup-syntax.md b/docs/contributing/markup-syntax.md index 6aec45d1d..44a29c030 100644 --- a/docs/contributing/markup-syntax.md +++ b/docs/contributing/markup-syntax.md @@ -1,12 +1,12 @@ --- html_meta: - "description": "Authors guide to Sphinx, MyST and markdown" - "keywords": "Sphinx, MyST, markdown" + "description": "Guide to Sphinx, MyST, and Markdown" + "keywords": "Sphinx, MyST, Markdown" --- # Guide for Authors -## MyST markdown, Sphinx +## MyST, Markdown, Sphinx We use [MyST, or Markedly Structured Text](https://myst-parser.readthedocs.io/en/latest/), a rich and extensible flavor of Markdown, for authoring training documentation. From ac8ce7841629e648d2cf5f1b70a4234e502a19b2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 13:36:04 -0700 Subject: [PATCH 07/34] Remove translation-related packages polib, transifex-client. Remove sphinxcontrib-websupport because docs are static and not integrated into a web application. Sort items. --- requirements.txt | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/requirements.txt b/requirements.txt index a94645092..856eb3082 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,14 +1,11 @@ -c constraints.txt -sphinx-book-theme +Sphinx +jsx-lexer +lesscpy linkify-it-py +myst-parser +sphinx-book-theme sphinx-copybutton sphinx-togglebutton -jsx-lexer -myst-parser -polib -Sphinx sphinxcontrib-spelling -sphinxcontrib-websupport -transifex-client -lesscpy From e5bffb1cd5bf65967af2e30af7e04bbf372b4e90 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 13:42:39 -0700 Subject: [PATCH 08/34] Makefile: Fix whitespace, set output to $(BUILDDIR) instead of hard-coded `log`, add linkcheck and spellcheck to `make test`. conf.py: Sort extensions Disable smartquotes Remove obsolete .rst as a source_suffix Remove obsolete exclude_patterns, now that we have the docs in a subdirectory `docs/`, configured `Makefile` to put items into `$(BUILDDIR)` Remove redundant about.md file --- about.md | 3 --- docs/Makefile | 14 +++++++------- docs/conf.py | 26 ++++++++++---------------- 3 files changed, 17 insertions(+), 26 deletions(-) delete mode 100644 about.md diff --git a/about.md b/about.md deleted file mode 100644 index fe6a33521..000000000 --- a/about.md +++ /dev/null @@ -1,3 +0,0 @@ -# About - -[Plone Training](https://training.plone.org) is a collection of different trainings, developed and created by the Plone Community. diff --git a/docs/Makefile b/docs/Makefile index 7c546184b..e2dba2633 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -39,9 +39,9 @@ help: @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " spellcheck to run spellcheck against the documentation (if enabled)" - @echo " test run spell and link check in order to test" - @echo " deploy run clean and html, to get a clean build" + @echo " spellcheck to run spellcheck against the documentation (if enabled)" + @echo " test to run spell and link check in order to test" + @echo " deploy to run clean and html, to get a clean build" @echo " presentation to make HTML in presentation mode" .PHONY: clean @@ -192,14 +192,14 @@ linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ - "or in log/linkcheck/output.txt." + "or in $(BUILDDIR)/linkcheck/output.txt." .PHONY: spellcheck spellcheck: - LANGUAGE=$* $(SPHINXBUILD) -b spelling -j 4 $(ALLSPHINXOPTS) log/spellcheck/$* + LANGUAGE=$* $(SPHINXBUILD) -b spelling -j 4 $(ALLSPHINXOPTS) $(BUILDDIR)/spellcheck/$* @echo @echo "Spellcheck is finished; look for any errors in the above output " \ - " or in log/spellcheck/output.txt." + " or in $(BUILDDIR)/spellcheck/output.txt." .PHONY: doctest doctest: @@ -208,7 +208,7 @@ doctest: "results in $(BUILDDIR)/doctest/output.txt." .PHONY: test -test: clean +test: clean linkcheck spellcheck .PHONY: deploy deploy: clean html diff --git a/docs/conf.py b/docs/conf.py index 55d13a4c1..5a98ae476 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,12 +55,12 @@ # They can be extensions coming with Sphinx (named "sphinx.ext.*") # or your custom ones. extensions = [ - "sphinx_copybutton", - "sphinx.ext.intersphinx", + "myst_parser", "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", "sphinx.ext.todo", + "sphinx_copybutton", "sphinxcontrib.spelling", - "myst_parser", ] # For more information see: @@ -73,6 +73,13 @@ # instead of ```. ] +# If true, the Docutils Smart Quotes transform, originally based on SmartyPants +# (limited to English) and currently applying to many languages, will be used +# to convert quotes and dashes to typographically correct entities. +# Note to maintainers: setting this to `True` will cause contractions and +# hyphenated words to be marked as misspelled by spellchecker. +smartquotes=False + # The name of the Pygments (syntax highlighting) style to use. # pygments_style = "sphinx.pygments_styles.PyramidStyle" pygments_style = "sphinx" @@ -104,7 +111,6 @@ # The suffix of source filenames. source_suffix = { - ".rst": "restructuredtext", ".md": "markdown", } @@ -118,19 +124,7 @@ # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ - ".github/CONTRIBUTING.md", - "CHANGES.rst", - "README.rst", - "_build", - "bin", - "env", - "include", - "lib", - "local", - "log", "spelling_wordlist.txt", - "node_modules", - "about.md", ] From b3454b5a8c95c82fb65d0ef45bc0903a6a0ae74f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 13:43:59 -0700 Subject: [PATCH 09/34] Add a few good words for spellcheck --- docs/spelling_wordlist.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index b4597ad92..9f9f50067 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -1,4 +1,6 @@ acl +add-on +add-ons addon addons admin @@ -8,6 +10,7 @@ Ansible api ary autoform +Barceloneta Barebone blobstorage Bluebream @@ -20,6 +23,7 @@ btw buildout Buildouts buildouts +built-in bzr Casali cfg @@ -59,6 +63,7 @@ eea Einsteigerkurs eventhandlers extendable +extensibility facettednavigation fallback faq @@ -79,6 +84,7 @@ gitlab gomez google grep +Gunicorn haproxy Herstory hg @@ -118,6 +124,7 @@ localhost logfiles longtest macagua +macOS Mailserver Metadata metadata @@ -141,6 +148,7 @@ online org outlier pageview +Pastanaga pattern Patternslib pbauer @@ -163,6 +171,7 @@ Portlet portlets Portlets postrelease +POSIX pre precompiler prepending @@ -171,7 +180,9 @@ py pypi pypirc quickinstaller +Rapido redmine +Redux refactor release renderers @@ -214,6 +225,8 @@ Todo Todos toLocalizedTime toolbar +trainings +Transmogrifier travis ttw UI @@ -223,6 +236,7 @@ url usenames Username username +uWSGI viewlet Viewlet viewlets @@ -230,10 +244,13 @@ Viewlets viewlets Viewlets VirtualBox +Volto votable voteable Walkthrough +webpack webserver +Werkzeug wf Workflow workflow @@ -242,10 +259,12 @@ workflows XDV Xephyr xml +XPath xvfb xxx yml zc +ZCatalog zcml zeoclients zeoserver From f41717e0ddab8750aae777dfb0d9087461c009d8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 13:49:32 -0700 Subject: [PATCH 10/34] Remove unused, undocumented, and unsupported spell checking tools --- docs/.textlintrc | 99 ---------------------------------------------- docs/.ttd-lintrc | 7 ---- docs/badwords.txt | 2 - docs/tests/lint.sh | 18 --------- docs/word-lint.txt | 5 --- 5 files changed, 131 deletions(-) delete mode 100644 docs/.textlintrc delete mode 100644 docs/.ttd-lintrc delete mode 100644 docs/badwords.txt delete mode 100755 docs/tests/lint.sh delete mode 100644 docs/word-lint.txt diff --git a/docs/.textlintrc b/docs/.textlintrc deleted file mode 100644 index e3ba1a865..000000000 --- a/docs/.textlintrc +++ /dev/null @@ -1,99 +0,0 @@ -{ - "plugins": [ - "rst" - ], - "rules": { - "write-good": { - "so": true, - "thereIs": false, - "cliches": false, - "weasel": false, - "tooWordy": false, - "adverb": false, - "passive": false - }, - // "rousseau": { - // "showLevels": [ - // "error" - // ], - // "ignoreTypes": [ - // "sentence:uppercase", - // "passive", - // "weasel" - // ] - // }, - "max-number-of-lines": { - "max" : 999 - }, - "unexpanded-acronym": { - "ignore_acronyms": [ - "AWS", - "CLI", - "NFS", - "BSD", - "SMTP", - "EBS", - "ZEO", - "ZODB", - "API", - "DNS", - "LTS", - "SSH", - "SES", - "YAML", - "JSON", - "URL", - "IAM", - "CPU", - "SPAM", - "TASK", - "RHEL", - "ZMI", - "XML", - "ZCML", - "CMF", - "FSM", - "TODO", - "HTTP", - "TTW", - "LESS", - "CSS", - "HTML", - "PEP", - "DOM" - ] - }, - "terminology": { - // Load default terms (see terms.json in the repository) - "defaultTerms": false, - // Syntax elements to skip. Overrides the default - "skip": ["Blockquote"], - // List of terms - "terms": [ - // Exact spelling including the case - "JavaScript", - "ESLint", - "Sass", - // "Less", - "npm", - "VirtualBox", - "OpsWorks", - "CloudFormation", - // RegExp (case-insensitive) → replacement - ["front[- ]end(\\w*)", "frontend$1"], - ["back[- ]end(\\w*)", "backend$1"], - ["web[- ]?site(s?)", "site$1"], - ["hot[- ]key", "hotkey"], - ["repo\\b", "repository"], - ["CLI tool(s?)", "command line tool$1"], - ["build system(s?)", "build tool$1"], - ["id['’]?s", "IDs"], - ["(\\w+[^.?!]\\)? )webpack", "$1webpack"], - ["(\\w+[^.?!]\\)? )internet", "$internet"], - ["OS X", "macOS"], - ["Mac ?OS", "macOS"], - ["React[ .]js", "React"] - ] - } - } -} diff --git a/docs/.ttd-lintrc b/docs/.ttd-lintrc deleted file mode 100644 index b574f3a9d..000000000 --- a/docs/.ttd-lintrc +++ /dev/null @@ -1,7 +0,0 @@ -Github -Javascript -Obviously -obviously -Cloudformation -Virtualbox -in order diff --git a/docs/badwords.txt b/docs/badwords.txt deleted file mode 100644 index 05869797e..000000000 --- a/docs/badwords.txt +++ /dev/null @@ -1,2 +0,0 @@ -bunch -stuff diff --git a/docs/tests/lint.sh b/docs/tests/lint.sh deleted file mode 100755 index 014422c90..000000000 --- a/docs/tests/lint.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/bin/bash -set -e - - -CHANGED_FILES=$(git diff-index --name-only HEAD --cached | grep \.rst$) - -if [ -n "$CHANGED_FILES" ]; then - while read -r fname; do - echo Testing: "$fname" - docker run -v "${PWD}"/"$fname":/srv/docs:rw -v "${PWD}"/.ttd-lintrc:/srv/.ttd-lintrc testthedocs/plone-lint - echo Running write-good checks - docker run -v "${PWD}":/srv testthedocs/ttd-textlint "$fname" - done <<< "$CHANGED_FILES" - exit 0 -fi -exit 0 -# Check if last commit includes a rst file -#git diff-index --name-only HEAD --cached | grep \.rst$ diff --git a/docs/word-lint.txt b/docs/word-lint.txt deleted file mode 100644 index e71a86a42..000000000 --- a/docs/word-lint.txt +++ /dev/null @@ -1,5 +0,0 @@ -GMail -GitHub -JavaScript -CloudFormation -VirtualBox From 5cb3f501920bb269c1648d74c86c99435796b7a6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 14:01:39 -0700 Subject: [PATCH 11/34] Remove duplicate words --- docs/spelling_wordlist.txt | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 9f9f50067..d046d3d43 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -144,7 +144,6 @@ nocall omelette online Online -online org outlier pageview @@ -241,8 +240,6 @@ viewlet Viewlet viewlets Viewlets -viewlets -Viewlets VirtualBox Volto votable From 8e828e8bda7dfdfee83407f88267cfaec0f243a1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 14:15:55 -0700 Subject: [PATCH 12/34] Fix link to contributing --- README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 3b5cd3e59..abe902659 100644 --- a/README.rst +++ b/README.rst @@ -25,7 +25,7 @@ Different Plone Trainings: Documentation ============= -Documentation on how to use, build and contribute to the trainings can be found on the `Training Website `_ . +Documentation on how to use, build and contribute to the trainings can be found on the `Training Website `_ . The landing page @@ -50,5 +50,5 @@ If you are having issues, please let us know by opening an issue in our `Issue T License ======= -The project is licensed under the `Creative Commons Attribution 4.0 International License `_ by the `Plone Foundation `_ +The project is licensed under the `Creative Commons Attribution 4.0 International License `_ by the `Plone Foundation `_. From 105936e19569a1ddb6a3efec714ba2d0f685a7c0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 15:07:56 -0700 Subject: [PATCH 13/34] Fix warning after rst to myst conversion --- docs/mastering-plone/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mastering-plone/index.md b/docs/mastering-plone/index.md index 21ef327c2..efc720b15 100644 --- a/docs/mastering-plone/index.md +++ b/docs/mastering-plone/index.md @@ -33,7 +33,7 @@ intro case what_is_plone installation -../plone_training_config/instructions.rst +../plone_training_config/instructions.md features anatomy plone_versions From 50cc2f794e041c6c9038da6f6024d802a5176cc3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 16:34:09 -0700 Subject: [PATCH 14/34] Improve spacing around local navigation. Items that wrapped onto multiple lines looked like multiple items without this improvement. --- docs/_static/custom.css | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/_static/custom.css b/docs/_static/custom.css index f70296f74..eba175f3f 100644 --- a/docs/_static/custom.css +++ b/docs/_static/custom.css @@ -190,4 +190,10 @@ main.bd-content #main-content dl.simple dt + dd { overflow-x: hidden; color: rgba(0,0,0,.65); border-radius: 10px; +} + +/* Local navigation */ +li.nav-item.toc-entry { + line-height: 1.25em; + margin-bottom: 0.25em; } \ No newline at end of file From 314bcb0a5fe7835237e3b5db0cc0d993a3136644 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 16:57:09 -0700 Subject: [PATCH 15/34] lower the linkcheck_timeout to 5 seconds --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 5a98ae476..35fcffe82 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -103,7 +103,7 @@ r"https://www.linode.com", # linkcheck makes a HEAD request, which is 403 ] linkcheck_anchors = False -linkcheck_timeout = 30 +linkcheck_timeout = 5 # This is our wordlist with know words, like Github or Plone ... spelling_word_list_filename = "spelling_wordlist.txt" From a93e8f23833564364629ab884d91c9f05ce1e38f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 17:28:41 -0700 Subject: [PATCH 16/34] Bad developer added bad links to exclude from link check. I done fixed 'em. --- docs/angular/configuration.md | 2 +- docs/conf.py | 12 ++---------- docs/contributing/index.md | 2 +- docs/contributing/setup-author.md | 4 ++-- docs/gatsby/searchtraversal.md | 2 +- docs/mastering-plone-5/custom_search.md | 2 +- docs/mastering-plone-5/intro.md | 6 +++--- docs/mastering-plone/custom_search.md | 2 +- docs/mastering-plone/intro.md | 2 +- docs/plone_training_config/instructions.md | 2 +- docs/plone_training_config/instructions_plone5.md | 2 +- docs/solr/a-fancy-custom-search-page.md | 4 ++-- docs/solr/production-setup.md | 4 ++-- docs/solr/setup.md | 4 ++-- docs/solr/solr-configuration.md | 2 +- 15 files changed, 22 insertions(+), 30 deletions(-) diff --git a/docs/angular/configuration.md b/docs/angular/configuration.md index b16016665..ce3c9fe0c 100644 --- a/docs/angular/configuration.md +++ b/docs/angular/configuration.md @@ -55,7 +55,7 @@ That's how collective.themesitesetup gets enabled. Now we need to save our current Plone configuration into our theme. We need to use the `collective.themesitesetup` export feature available here: -. +`http://whatever.herokuapp.com/Plone/++theme++plonecustom/@@export-site-setup`. Obviously we do not need to export everything, in our current case we just want to get the comment feature related configuration and the content type configuration, so we just select `typeinfo` and `plone.app.registry`. diff --git a/docs/conf.py b/docs/conf.py index 35fcffe82..00ab779d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -89,17 +89,9 @@ linkcheck_ignore = [ r"http://localhost:\d+", r"http://127.0.0.1:8080", - r"http://wiki.apache.org", - r"https://wiki.apache.org", - r"https://www.vagrantup.com", - r"https://www.dipf.de/en/research/projects", - r"http://whatever.herokuapp.com", r"http://example.com", - r"http://lorempixel.com", - r"https://plonedemo.kitconcept.com/en/@search", - r"https://www.packtpub.com", - r"https://lucidworks.com", - r"https://twitter.com", # linkcheck redirects to mobile version + r"https://github.com/plone/training/issues/new/choose", # requires auth + # r"https://twitter.com", # linkcheck redirects to mobile version r"https://www.linode.com", # linkcheck makes a HEAD request, which is 403 ] linkcheck_anchors = False diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 8fde0e6b9..02fee96d7 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -31,7 +31,7 @@ Any method below is acceptable, but are listed in order of most likely to get a - [Create a new issue](https://github.com/plone/training/issues/new/choose). - Discuss during conferences, trainings, and other Plone events. - Ask on the [Plone Community Forum, Documentation topic](https://community.plone.org/c/documentation/13). -- Ask in the [Plone chat on Discord](https://discord.gg/zFY3EBbjaj). +- Ask in the [Plone chat on Discord](https://discord.com/invite/zFY3EBbjaj). As a convenience, at the top right of every page, there is a GitHub navigation menu. Tap, click, or hover over the GitHub Octocat icon for options. diff --git a/docs/contributing/setup-author.md b/docs/contributing/setup-author.md index 27599f8d6..3ab5c2cdb 100644 --- a/docs/contributing/setup-author.md +++ b/docs/contributing/setup-author.md @@ -172,8 +172,8 @@ and see a browser window opening on . ## Upgrade the vagrant and buildout to a new Plone-version -- In change [buildout.cfg](https://github.com/collective/training_buildout/blob/master/buildout.cfg) to extend from the new `versions.cfg` on -- Check if we should to update any versions in +- In change [buildout.cfg](https://github.com/collective/training_buildout/blob/master/buildout.cfg) to extend from the new `versions.cfg` on . +- Check if we should to update any versions in . - Commit and push the changes to the training_buildout - Modify the vagrant-setup by modifying {file}`plone_training_config/manifests/plone.pp`. Set the new Plone-version as `$plone_version` in line 3. - Test the vagrant-setup it by creating a new vagrant-box using the new config. diff --git a/docs/gatsby/searchtraversal.md b/docs/gatsby/searchtraversal.md index 545dd5e57..90e2c48d2 100644 --- a/docs/gatsby/searchtraversal.md +++ b/docs/gatsby/searchtraversal.md @@ -7,7 +7,7 @@ One of the strategies that we experimented with and adopted for the source-plugi ## Getting The Full List Of Content -Make a GET request to . +Make a GET request to `https://plonedemo.kitconcept.com/en/@search`. ```json { diff --git a/docs/mastering-plone-5/custom_search.md b/docs/mastering-plone-5/custom_search.md index 4271ddc93..61efa9fab 100644 --- a/docs/mastering-plone-5/custom_search.md +++ b/docs/mastering-plone-5/custom_search.md @@ -30,7 +30,7 @@ and dynamically. Examples: -- https://www.dipf.de/en/research/projects +- https://www.dipf.de/en/research/current-projects - https://www.mountaineers.org/courses/courses-clinics-seminars - https://www.dyna-jet.com/highpressurecleaner diff --git a/docs/mastering-plone-5/intro.md b/docs/mastering-plone-5/intro.md index 990ff7527..6ba97741d 100644 --- a/docs/mastering-plone-5/intro.md +++ b/docs/mastering-plone-5/intro.md @@ -109,7 +109,7 @@ You should also be able to find out where to look for instructions to do tasks w You will know most of the core technologies involved in Plone programming. If you want to become a professional Plone developer or a highly sophisticated Plone integrator you should -definitely read [Martin Aspeli's book](https://www.packtpub.com/web-development/professional-plone-4-development) +definitely read [Martin Aspeli's book](https://www.packtpub.com/product/professional-plone-4-development/9781849514422) and then re-read it again while actually doing a complex project. (plone5-intro-classroom-protocol)= @@ -161,6 +161,6 @@ You can use this presentation to copy & paste the code but you will memorize mor ## Further Reading -- [Martin Aspeli: Professional Plone4 Development](https://www.packtpub.com/web-development/professional-plone-4-development) -- [Practical Plone](https://www.packtpub.com/web-development/practical-plone-3-beginners-guide-building-powerful-websites) +- [Martin Aspeli: Professional Plone4 Development](https://www.packtpub.com/product/professional-plone-4-development/9781849514422) +- [Practical Plone](https://www.packtpub.com/product/practical-plone-3-a-beginner-s-guide-to-building-powerful-websites/9781847191786) - [Zope Page Templates Reference](https://zope.readthedocs.io/en/latest/zopebook/AppendixC.html) diff --git a/docs/mastering-plone/custom_search.md b/docs/mastering-plone/custom_search.md index 0ce5d5518..fbc8e8bab 100644 --- a/docs/mastering-plone/custom_search.md +++ b/docs/mastering-plone/custom_search.md @@ -35,7 +35,7 @@ and dynamically. Examples: -- +- - - diff --git a/docs/mastering-plone/intro.md b/docs/mastering-plone/intro.md index 4159f57cc..2086f8a56 100644 --- a/docs/mastering-plone/intro.md +++ b/docs/mastering-plone/intro.md @@ -63,5 +63,5 @@ You can use this presentation to copy & paste the code but you will memorize mor ## Further Reading -- [Martin Aspeli: Professional Plone4 Development](https://www.packtpub.com/web-development/professional-plone-4-development) +- [Martin Aspeli: Professional Plone4 Development](https://www.packtpub.com/product/professional-plone-4-development/9781849514422) - [The Zope Book](https://zope.readthedocs.io/en/latest/zopebook/) diff --git a/docs/plone_training_config/instructions.md b/docs/plone_training_config/instructions.md index e3fe4542c..613202384 100644 --- a/docs/plone_training_config/instructions.md +++ b/docs/plone_training_config/instructions.md @@ -326,7 +326,7 @@ We use VirtualBox 6.0.x ### Install and configure Vagrant -Get the latest version from for your operating system and install it. +Get the latest version from for your operating system and install it. Now your system has a command {command}`vagrant` that you can run in the terminal. diff --git a/docs/plone_training_config/instructions_plone5.md b/docs/plone_training_config/instructions_plone5.md index bfccef136..11183ed20 100644 --- a/docs/plone_training_config/instructions_plone5.md +++ b/docs/plone_training_config/instructions_plone5.md @@ -182,7 +182,7 @@ We use VirtualBox 6.0.x ### Install and configure Vagrant -Get the latest version from for your operating system and install it. +Get the latest version from for your operating system and install it. Now your system has a command {command}`vagrant` that you can run in the terminal. diff --git a/docs/solr/a-fancy-custom-search-page.md b/docs/solr/a-fancy-custom-search-page.md index ee34d6497..eec70355a 100644 --- a/docs/solr/a-fancy-custom-search-page.md +++ b/docs/solr/a-fancy-custom-search-page.md @@ -165,7 +165,7 @@ additional-solrconfig = The spell check component can return a list of alternative spelling suggestions. - http://wiki.apache.org/solr/SpellCheckComponent + https://wiki.apache.org/solr/SpellCheckComponent --> @@ -231,7 +231,7 @@ additional-solrconfig = IN OTHER WORDS, THERE IS REALLY GOOD CHANCE THE SETUP BELOW IS NOT WHAT YOU WANT FOR YOUR PRODUCTION SYSTEM! - See http://wiki.apache.org/solr/SpellCheckComponent for details + See https://wiki.apache.org/solr/SpellCheckComponent for details on the request parameters. --> diff --git a/docs/solr/production-setup.md b/docs/solr/production-setup.md index 828cde58a..c8e18f9ff 100644 --- a/docs/solr/production-setup.md +++ b/docs/solr/production-setup.md @@ -22,7 +22,7 @@ default-core-name : Optional and deprecated. This option controls which core is set as the default for incoming requests that do not specify a core name. - This corresponds to the `defaultCoreName` option described at . + This corresponds to the `defaultCoreName` option described at . *No longer* used in Solr 5. An example for a multi-core configuration you can find in the documentation of `collective.recipe.solrinstance`: @@ -55,7 +55,7 @@ To make this happen you have to consider a couple of things: ## Further reading -Solr is documented in its own [Wiki](https://wiki.apache.org/solr/). +Solr is documented in its own [Wiki](https://cwiki.apache.org/confluence/display/solr/). ```{seealso} https://solr.apache.org/guide/6_6/ diff --git a/docs/solr/setup.md b/docs/solr/setup.md index 16ba3a944..aae319fea 100644 --- a/docs/solr/setup.md +++ b/docs/solr/setup.md @@ -151,7 +151,7 @@ Solr defines its schema in a big XML file called `schema.xml`. The main part is copyField: copy content to another field, e.g. copy title, description and subject to default. ```{seealso} - +https://cwiki.apache.org/confluence/display/solr/SchemaXml#Common_field_options ``` This is the bare minimum for configuring Solr. There are more options supported by Solr, @@ -213,7 +213,7 @@ for indexing and searching. #### Highlighting - + > - Highlighting fields > - Highlight formatter: pre diff --git a/docs/solr/solr-configuration.md b/docs/solr/solr-configuration.md index 450812c73..8dd0e14cf 100644 --- a/docs/solr/solr-configuration.md +++ b/docs/solr/solr-configuration.md @@ -77,7 +77,7 @@ https://solr.apache.org/guide/8_2/understanding-analyzers-tokenizers-and-filters ``` ```{seealso} -https://wiki.apache.org/solr/LanguageAnalysis +https://cwiki.apache.org/confluence/display/solr/LanguageAnalysis ``` A short example to include a German stemming factory is here: From dadf190e60459623307e10e7f6c8276b1776f750 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 17:53:35 -0700 Subject: [PATCH 17/34] Use em dash, not double hyphen --- docs/javascript/exercises/10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/javascript/exercises/10.md b/docs/javascript/exercises/10.md index 6500035c4..c28ba04c4 100644 --- a/docs/javascript/exercises/10.md +++ b/docs/javascript/exercises/10.md @@ -193,4 +193,4 @@ You can also toggle development mode on and off, click save, to force configurat In this exercise, there is no special distinction between development and production builds. -Webpack re-builds the resource on every change for you and the JavaScript build file is not added to any bundle--it is loaded for this particular page. +Webpack re-builds the resource on every change for you and the JavaScript build file is not added to any bundle—it is loaded for this particular page. From 1681b5e9b76870aa13c8cc31fc933e30a51f67c9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 12 Sep 2021 17:54:26 -0700 Subject: [PATCH 18/34] Twitter does not redirect --- docs/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 00ab779d7..5931698ee 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,7 +91,6 @@ r"http://127.0.0.1:8080", r"http://example.com", r"https://github.com/plone/training/issues/new/choose", # requires auth - # r"https://twitter.com", # linkcheck redirects to mobile version r"https://www.linode.com", # linkcheck makes a HEAD request, which is 403 ] linkcheck_anchors = False From abbae66102b98c16b64953d421060a6739c2ec2d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 13 Sep 2021 00:52:15 -0700 Subject: [PATCH 19/34] Add gulp-cli to package.json --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 4672c1804..5314d7e79 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "homepage": "https://github.com/plone/training#readme", "devDependencies": { "browser-sync": "^2.26.7", - "gulp": "^4.0.2" + "gulp": "^4.0.2", + "gulp-cli": "^2.3.0" } } From 2837c789696e1eac2ce14a3785c7bdff75a8eb33 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 13 Sep 2021 00:53:28 -0700 Subject: [PATCH 20/34] mail server is two words change lexer to shell --- docs/mastering-plone-5/about_mastering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mastering-plone-5/about_mastering.md b/docs/mastering-plone-5/about_mastering.md index 5a1ef4ade..463161dbd 100644 --- a/docs/mastering-plone-5/about_mastering.md +++ b/docs/mastering-plone-5/about_mastering.md @@ -275,7 +275,7 @@ $ open _build/html/index.html ### Technical set up to do before a training (as a trainer) -- Prepare a mailserver for the user registration mail (See {ref}`plone5-features-mailserver-label`) +- Prepare a mail server for the user registration mail (See {ref}`plone5-features-mailserver-label`) - If you do only a part of the training (Advanced) prepare a database with the steps of the previous sections. Be aware that the file- and blobstorage in the Vagrant box is here: /home/vagrant/var/ (not at the buildout path /vagrant/buildout/) ### Upgrade the vagrant and buildout to a new Plone-version From 3264cdb204c2a969bfa6edf42f25a27562cb65a7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 13 Sep 2021 00:53:52 -0700 Subject: [PATCH 21/34] Add reStructuredText to Glossary --- docs/glossary.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index 83f6c6b0c..9fc535933 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -210,6 +210,10 @@ React [React](https://reactjs.org/) is a JavaScript library for building user interfaces. Volto, the frontend for Plone 6, uses React. +reStructuredText + [reStructuredText (rST)](https://docutils.sourceforge.io/rst.html) is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. + The Training documentation was written in reStructuredText originally, then converted to {term}`MyST` in 2021. + MyST [Markedly Structured Text (MyST)](https://myst-parser.readthedocs.io/en/latest/) is a rich and extensible flavor of Markdown, for authoring training documentation. From 1b1590645d506e5b2438455b088aa4cf5f8e11bc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 13 Sep 2021 00:54:33 -0700 Subject: [PATCH 22/34] Reorganize contributing directory to focus on target audiences. --- docs/contributing/authors.md | 270 +++++++++++++++++++++++++++++++ docs/contributing/index.md | 65 ++++---- docs/contributing/setup-build.md | 100 ++++++++++++ docs/contributing/trainers.md | 58 +++++++ 4 files changed, 466 insertions(+), 27 deletions(-) create mode 100644 docs/contributing/authors.md create mode 100644 docs/contributing/setup-build.md create mode 100644 docs/contributing/trainers.md diff --git a/docs/contributing/authors.md b/docs/contributing/authors.md new file mode 100644 index 000000000..1ff4bba4f --- /dev/null +++ b/docs/contributing/authors.md @@ -0,0 +1,270 @@ +--- +html_meta: + "description": "Authors' guide to writing Plone Trainings. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." + "keywords": "Plone, Trainings, SEO, meta, presentation, exercises, solutions, spellcheck, linkcheck, lexer" +--- + +(authors-guide-label)= + +# Authors Guide + +This guide is for authors of Training documentation. +It covers configuring quality checks and syntax for writing markup that is of particular interest to authors. +For general markup syntax, see {doc}`markup-syntax`. + + +(authors-html-meta-data-label)= + +## HTML meta data + +All documents must have an `html_meta` directive at the top of every page. +When rendered to HTML, it inserts `` tags for search engine optimization. +Authors should include at least `description` and `keywords` meta tags. + +The following is an example of `html_meta`. + +```md +--- +html_meta: + "description": "Authors' guide to writing Plone Trainings. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors." + "keywords": "Plone, Trainings, SEO, meta, presentation, exercises, solutions, spellcheck, linkcheck, lexer" +--- +``` + +This renders in the HTML `` section as follows. + +```html + + +``` + +(authors-presentation-markup-label)= + +## Writing Presentation Markup + +The `presentation` build creates an abbreviated version of the documentation. +It is designed for projectors which are typically low resolution and have limited screen space. +Authors should use bullet points instead of long narrative text. + +The command `make presentation` as described in {ref}`setup-build-make-presentation-label` is implemented through the [Sphinx `only` directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only). + +The `presentation` builder is configured in {file}`docs/Makefile` using the [`sphinx-build` flag `-t`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-t). + +To show something in the `presentation` build and hide in the `html` build, use the following syntax. + +````md +```{only} presentation +> This will appear only in the presentation build. +``` +```` + +This will render as follows. + +```{only} presentation +> This will appear only in the presentation build. +``` + +To hide something in the `presentation` build and show in the `html` build, use the following syntax. + +````md +```{only} not presentation +> I am hiding from the presentation build. +``` +```` + +This will render as follows. + +```{only} not presentation +> I am hiding from the presentation build. +``` + + +(authors-exercises-and-solutions-label)= + +## Writing Exercises and Solutions + +We use a custom JavaScript in {file}`docs/_templates/page.html` to hide and show solutions to exercises in the trainings. + +This makes use of the unique docutils [`admonition` directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html#generic-admonition) which allows a custom title. +We also use a special `:class: toggle` option for the directive. + +Note that the markup uses [MyST nested directives](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#nesting-directives). + +`````md +````{admonition} This is a title +:class: toggle + +```{code-block} python +:lineno-start: 10 +:emphasize-lines: 1, 3 + +a = 2 +print("my 1st line") +print(f"my {a}nd line") +``` + +```` +````` + +This will render as follows. + +````{admonition} This is a title +:class: toggle + +```{code-block} python +:lineno-start: 10 +:emphasize-lines: 1, 3 + +a = 2 +print("my 1st line") +print(f"my {a}nd line") +``` + +```` + +(authors-quality-checks-label)= + +## Quality checks + +We strive for high quality documentation, setting the following minimum standards. + + +(authors-markup-syntax-label)= + +### Markup syntax must be valid + +See both the specific markup syntax above and general markup in {doc}`markup-syntax`. + +To validate markup, run the following command. + +```shell +make html +``` + +Open `/_build/html/index.html` in a web browser. + + +(authors-english-label)= + +### American English Spelling, Grammar, and Syntax + +Spellings are enforced through [`spellcheck`](https://sphinxcontrib-spelling.readthedocs.io/en/latest/index.html). +We use the locale `en_US`. + +{file}`docs/Makefile`, {file}`docs/conf.py`, and {file}`docs/spelling_wordlist.txt`. + +Authors should add new words and proper names using correct casing to {file}`docs/spelling_wordlist.txt`, sorted alphabetically. + +See [default settings and configuration options](https://sphinxcontrib-spelling.readthedocs.io/en/latest/customize.html). + +To validate spelling, run the following command. + +```shell +make spellcheck +``` + +Open `/_build/spellcheck/` for each training's misspellings. + +Because it is difficult to automate good English grammar and syntax, we do not strictly enforce it. +We also understand that contributors might not be fluent in English. +We encourage contributors to make a reasonable effort, and to seek help from community members who are fluent in English. +Please ask! + + +(authors-linkcheck-label)= + +### All links must be valid + +Valid links are enforced automatically through Sphinx's `linkcheck` builder. + +[Configuration of the `linkcheck` builder](https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder) is in {file}`docs/Makefile` and {file}`docs/conf.py`. + +`linkcheck_ignore` supports regular expression syntax. + +When authors add a link to their training, it must be a valid public URL without requiring authentication. + +If it is not a valid link, or is private or local, then you must exclude it from `linkcheck` by wrapping it in single backticks. + +```md +Visit the URL `http://www.example.com` for an example. +``` + +This will render as follows. + +> Visit the URL `http://www.example.com` for an example. + +If a link has succumbed to bit rot, then try finding the most recently scraped version on the [Internet Archive Wayback Machine](https://web.archive.org/), and update the link. + +To validate links, run the following command. + +```shell +make linkcheck +``` + +Open `/_build/presentation/output.txt` for a list of broken links. + +```{danger} +Please do not abuse `linkcheck_ignore`. + +There is a special place in hell reserved for contributors who do not bother to update bad links, either dead ones or redirects, causing `linkcheck` to fail. +And there is a doubly punishing place for those who disable `linkcheck` because there are too many bad links. + +Please do not be "that person". +``` + + +(authors-syntax-highlighting-label)= + +### Syntax highlighting + +Sample code blocks perform syntax highlighting through Pygments. +Authors must use a proper [Pygments lexer](https://pygments.org/docs/lexers/) and not generate warnings. + +Avoid adding comments to code snippets, unless you use valid comment syntax for that language. +JSON does not allow comments. + +Do not indicate elided or omitted code with ellipses (`...` or `…`). +These are almost never valid syntax and will cause syntax highlighting to fail for the code block. + +Some lexers are less than perfect. +If your code block does not highlight well, then consider specifying a less ambitious lexer, such as `text`. + +`jsx` has a complex syntax that is difficult to parse. +We have high hopes for the project [`jsx-lexer`](https://github.com/fcurella/jsx-lexer). +We include it in our `requirements.txt` file. +Please contribute to its further development. + +The lexers `html+ng2`, `scss`, `http`, `less` are also suboptimal and particular. + +To validate code block syntax, run the following command. + +```shell +make html +``` + +An [online demo of all lexers that Pygments supports](https://pygments.org/demo/) may be helpful to test out your code blocks and snippets for syntax highlighting. + + +## Synchronize the Browser While Editing + +Use gulp to view changes in the browser while editing documentation. + +Install the gulp command line utility. + +```shell +npm install --save-dev gulp-cli +``` + +Install the gulp project. + +```shell +npm install --save-dev +``` + +Run gulp while editing the training documentation. + +```shell +gulp +``` + +Your system's default browser will launch and open a window http://localhost:3002/. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 02fee96d7..a57636eec 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,9 +1,20 @@ +--- +html_meta: + "description": "Contributing to Plone Trainings Documentation." + "keywords": "Plone, Trainings, Plone Contributor Agreement, License, Code of Conduct" +--- + +(contributing-index-label)= + # Contributing to Plone Trainings Documentation This document describes how to contribute to the Plone Trainings Documentation. Contributions to the Plone Trainings documentation are welcome. + +(contributing-permission-to-publish-label)= + ## Granting permission to publish Before you contribute, you must give permission to publish your contribution according to the license we use. @@ -20,7 +31,9 @@ The Plone Trainings Documentation is licensed under the [Creative Commons Attrib A copy of the license is included in the root of this repository. -## GitHub +(contributing-manage-on-github-label)= + +## Managing contributions on GitHub Contributions are managed through the [Training repository on GitHub](https://github.com/plone/training). @@ -48,30 +61,33 @@ Next edit files, commit your changes, push them to the remote repository, and su Members who subscribe to the repository will receive a notification and review your request. -## Contribution quality requirements +(contributing-roles-label)= + +## Contributor Roles + +Contributors to the Training docs may perform one or many roles. -Although we perform automatic testing of the documentation build through GitHub Actions with every pull request, you can catch errors and warnings by building the documentation locally. -See [TBD] for instructions on how to set up and build the documentation. +- **Plone users and developers** use this documentation because it is accurate and actively maintained. + People in these roles typically contribute minor corrections. + They should read {doc}`setup-build` and {doc}`markup-syntax`. +- **Authors** create the Training documentation. + They should read {doc}`setup-build` and {doc}`markup-syntax`. + They should also read {doc}`authors` for guidance and tips for writing good Training documentation. +- **Trainers** should read {doc}`setup-build`, {doc}`trainers`, and the trainings in {doc}`/plone_training_config/instructions` and {doc}`/teachers-training/index`. + These documents help trainers prepare for a successful training experience. -We strive for high quality documentation, setting the following minimum standards. -- Markup syntax must be valid. - See [TBD] for details. -- Good English grammar, spelling, and syntax. - Any locale of English is fine. +(contributing-quality-requirements-label)= - We understand that contributors might not be fluent in English. - Community members who are fluent in English are available to help. +## Documentation quality requirements - Certain spellings are enforced through `TBD`. - See [TBD] for details. -- All links must be valid. - This is enforced through `linkcheck`. - See [TBD] for details. -- The documentation must build successfully without warnings. - We may exempt this requirement for specific cases. +We use GitHub Actions with every pull request to enforce Training documentation quality. +We recommend that you build the documentation locally to catch errors and warnings early on. +See {doc}`setup-build` for instructions for how to set up and build the documentation and to run quality checks. +(contributing-code-of-conduct-label)= + ## Code of Conduct The Plone Foundation has published a [Code of Conduct](https://plone.org/foundation/materials/foundation-resolutions/code-of-conduct). @@ -85,13 +101,8 @@ maxdepth: 2 hidden: true --- -instructions -setup_author +setup-build +markup-syntax +trainers +authors ``` - -Changes to pages: - -- index (general contributing) -- markup-syntax (rename of instructions) -- setup-build (part from setup_author) -- trainers (part from setup_author) diff --git a/docs/contributing/setup-build.md b/docs/contributing/setup-build.md new file mode 100644 index 000000000..9a5c7b135 --- /dev/null +++ b/docs/contributing/setup-build.md @@ -0,0 +1,100 @@ +(setup-build-label)= + +# Building and Checking the Quality of Documentation + +This document covers how to build the Training documentation and check it for quality. + + +(setup-build-installation-label)= + +## Installation + +Install [Enchant](https://abiword.github.io/enchant/) to check spelling. + +**macOS** + +```shell +brew install enchant +``` + +**Ubuntu** + +```shell +sudo apt-get install enchant +``` + +Clone the Training repository, then create and activate a virtual environment, and install project dependencies. + +```shell +git clone https://github.com/plone/training.git +cd training +python -m venv . +source bin/activate +pip install -r requirements.txt +``` + + +(setup-build-available-documentation-builds-label)= + +## Available documentation builds + +All build and check documentation commands use the file `docs/Makefile`. +Your working directory should be `docs/` when issuing any of the commands. + +To see all available builds: + +```shell +make help +``` + + +### `html` + +`html` is the long narrative version used for the online documentation and by the trainer. + +```shell +make html +``` + +Open `/_build/html/index.html` in a web browser. + + +(setup-build-make-presentation-label)= + +### `presentation` + +`presentation` is an abbreviated version of the documentation. +It is designed for projectors which are typically low resolution and have limited screen space. +Trainers may present this version using a projector during a training. + +```shell +make presentation +``` + +Open `/_build/presentation/index.html` in a web browser. + +Authors should read {ref}`authors-presentation-markup-label` for how to write markup for the presentation build. + + +### `linkcheck` + +`linkcheck` checks all links. +See {ref}`authors-linkcheck-label` for configuration. + +```shell +make linkcheck +``` + +Open `/_build/presentation/output.txt` for a list of broken links. + + +### `spellcheck` + +`spellcheck` checks the spelling of words +See {ref}`authors-english-label` for configuration. + +```shell +make spellcheck +``` + +Open `/_build/spellcheck/` for each training's misspellings. diff --git a/docs/contributing/trainers.md b/docs/contributing/trainers.md new file mode 100644 index 000000000..6db2f88f6 --- /dev/null +++ b/docs/contributing/trainers.md @@ -0,0 +1,58 @@ +--- +html_meta: + "description": "Using the documentation for a training" + "keywords": "Plone, Trainings" +--- + +(contributing-trainers-label)= + +# Using the documentation for a training + +Feel free to organize a training yourself. +Please be so kind to contribute any bug fixes or enhancements you made to the documentation for your training. + +Trainers should read {doc}`setup-build` and the trainings in {doc}`/plone_training_config/instructions` and {doc}`/teachers-training/index`. +These documents help trainers prepare for a successful training experience. + + +## Technical set up to do before a training (as a trainer) + +```{important} +Much of this section is duplicated in {file}`/mastering-plone/about_mastering.md` and {file}`/mastering-plone-5/about_mastering.md`. +We should purge duplicitous content, and use references to a primary source. +``` + +- Prepare a mail server for the user registration mail (See {ref}`features-mailserver-label`) +- If you do only a part of the training (Advanced), prepare a database with the steps of the previous sections. Be aware that the file and blobstorage in the Vagrant box is at `/home/vagrant/var/` and not at the buildout path `/vagrant/buildout/`. + +## Upgrade the vagrant and buildout to a new Plone-version + +```{important} +Much of this section is duplicated in {file}`/mastering-plone/about_mastering.md` and {file}`/mastering-plone-5/about_mastering.md`. +We should purge duplicitous content, and use references to a primary source. +``` + + +- In change [buildout.cfg](https://github.com/collective/training_buildout/blob/master/buildout.cfg) to extend from the new `versions.cfg` on . +- Check if we should to update any versions in . +- Commit and push the changes to the training_buildout +- Modify the vagrant-setup by modifying {file}`plone_training_config/manifests/plone.pp`. Set the new Plone-version as `$plone_version` in line 3. +- Test the vagrant-setup it by creating a new vagrant-box using the new config. +- Create a new zip-file of all files in `plone_training_config` and move it to `_static`: + +```console +cd plone_training_config +zip -r ../_static/plone_training_config.zip * +``` + +- Commit and push the changes to + +## Train the trainer + +If you are a trainer there is a special mini training about giving technical trainings. +We really want this material to be used, re-used, expanded, and improved by Plone trainers world wide. + +These chapters don't contain any Plone specific advice. +There's background, theory, check lists, and tips for anyone trying to teach technical subjects. + +{doc}`/teachers-training/index` From a5c2461b91e0f970e501451ff1de36d2d9132457 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 13 Sep 2021 01:32:29 -0700 Subject: [PATCH 23/34] Remove as redundant --- docs/contributing/setup-author.md | 222 ------------------------------ 1 file changed, 222 deletions(-) delete mode 100644 docs/contributing/setup-author.md diff --git a/docs/contributing/setup-author.md b/docs/contributing/setup-author.md deleted file mode 100644 index 3ab5c2cdb..000000000 --- a/docs/contributing/setup-author.md +++ /dev/null @@ -1,222 +0,0 @@ -(about-use-label)= - -# Using the documentation for a training - -Feel free to organize a training yourself. -Please be so kind to contribute any bug fixes or enhancements you made to the documentation for your training. - -## Complete Mode and compact Presentation Mode - -The training is rendered using Sphinx and builds in two flavors: - -default -: The verbose version used for the online documentation and for the trainer. -: Build it in Sphinx with `make html` or use the online version. - -presentation -: An abbreviated version used for the projector during a training. -: It should use more bullet points than verbose text. -: Build it in Sphinx with `make presentation`. - -:::{note} -By prefixing an indented block of text or code with `.. only:: presentation` you can control -that this block is used for the presentation version only. - -To hide a block from the presentation version use `.. only:: not presentation` - -Content without a prefix will be included in both versions. -::: - - -## Exercises and Solutions - -Collapsed solutions of exercises: - -````{admonition} Complete code of the component Sed posuere consectetur est at lobortis. -:class: toggle - -```{code-block} jsx -:linenos: -:emphasize-lines: 2,4 - -import React from 'react'; -import { defineMessages, injectIntl } from 'react-intl'; -import { v4 as uuid } from 'uuid'; -import { omit, without } from 'lodash'; -``` -```` - -Be aware of the nested directives! Increase back ticks! - - ````{admonition} Complete code of the component - :class: toggle - - ```{code-block} jsx - :linenos: - :emphasize-lines: 2,4 - - import React from 'react'; - import { defineMessages, injectIntl } from 'react-intl'; - import { v4 as uuid } from 'uuid'; - import { omit, without } from 'lodash'; - ``` - ```` - - -## Building the documentation locally - -### Dependencies and new build - -Please make sure that you have [Enchant](https://abiword.github.io/enchant/) installed. This is needed for spell-checking. - -Install Enchant on macOS: - -```console -brew install enchant -``` - -Install Enchant on Ubuntu: - -```console -sudo apt-get install enchant -``` - -To build the documentation follow these steps: - -```console -git clone https://github.com/plone/training.git -cd training -python -m venv . -source bin/activate -``` - -Now install dependencies and build. - -```console -pip install -r requirements.txt -cd docs -make html -``` - -You can now open the output `_build/html/index.html` in your browser. - -To build the presentation version use `make presentation` instead of `make html`. You can open the presentation at `_build/presentation/index.html`. - -If you use macOS you can do: - -```console -open _build/html/index.html -``` - -In the case of Linux, Ubuntu for example you can do: - -```console -firefox _build/html/index.html -``` - -or with Chrome - -```console -google-chrome _build/html/index.html -``` - -**All steps in short** - -```console -git clone https://github.com/plone/training.git -cd training -python -m venv . -source bin/activate -pip install -r requirements.txt -cd docs -make html -``` - -## Update existing - -```bash -git pull -source bin/activate -make html -open _build/html/index.html -``` - -## Sync the browser while editing - -To watch the changes in browser while editing you can use gulp. - -Install once the gulp command line utility. - -```bash -npm install --global gulp-cli -``` - -Install once the gulp project with - -```bash -npm install -``` - -Run gulp when starting working on the training with - -```bash -gulp -``` - -and see a browser window opening on . - -## Technical set up to do before a training (as a trainer) - -- Prepare a mailserver for the user registration mail (See {ref}`features-mailserver-label`) -- If you do only a part of the training (Advanced) prepare a database with the steps of the previous sections. Be aware that the file- and blobstorage in the Vagrant box is here: /home/vagrant/var/ (not at the buildout path /vagrant/buildout/) - -## Upgrade the vagrant and buildout to a new Plone-version - -- In change [buildout.cfg](https://github.com/collective/training_buildout/blob/master/buildout.cfg) to extend from the new `versions.cfg` on . -- Check if we should to update any versions in . -- Commit and push the changes to the training_buildout -- Modify the vagrant-setup by modifying {file}`plone_training_config/manifests/plone.pp`. Set the new Plone-version as `$plone_version` in line 3. -- Test the vagrant-setup it by creating a new vagrant-box using the new config. -- Create a new zip-file of all files in `plone_training_config` and move it to `_static`: - -```console -cd plone_training_config -zip -r ../_static/plone_training_config.zip * -``` - -- Commit and push the changes to - - -## Train the trainer - -If you are a trainer there is a special mini training about giving technical trainings. These chapters don't contain any Plone specific advice. -There's background, theory, check lists, and tips for anyone trying to teach technical subjects: {doc}`/teachers-training/index` - -These chapters don't contain any Plone specific advice. -There's background, theory, check lists, and tips for anyone trying to teach technical subjects. - -{doc}`/teachers-training/index` - -(about-contribute-label)= - -## Contributing - -Everyone is **very welcome** to contribute. -Minor bug fixes can be pushed directly in the [repository](https://github.com/plone/training), -bigger changes should be made as [pull-requests](https://github.com/plone/training/pulls/) and discussed previously in tickets. - -(about-licence-label)= - -## License - -The Mastering Plone Training is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). - -Make sure you have filled out a [Contributor Agreement](https://plone.org/foundation/contributors-agreement). - -If you haven't filled out a Contributor Agreement, you can still contribute. -Contact the Documentation team, for instance via the [mailinglist](https://sourceforge.net/p/plone/mailman/plone-docs/) -or directly send a mail to - -Basically, all we need is your written confirmation that you are agreeing your contribution can be under Creative Commons. - -You can also add in a comment with your pull request "I, \, agree to have this published under Creative Commons 4.0 International BY". From c39f9f5d363b50bc007264b6426ecec63b5bb770 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Sep 2021 00:04:24 -0700 Subject: [PATCH 24/34] Remove unnecessary gulp command and flags --- docs/contributing/authors.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/contributing/authors.md b/docs/contributing/authors.md index 1ff4bba4f..8fdd660c2 100644 --- a/docs/contributing/authors.md +++ b/docs/contributing/authors.md @@ -249,16 +249,10 @@ An [online demo of all lexers that Pygments supports](https://pygments.org/demo/ Use gulp to view changes in the browser while editing documentation. -Install the gulp command line utility. - -```shell -npm install --save-dev gulp-cli -``` - Install the gulp project. ```shell -npm install --save-dev +npm install ``` Run gulp while editing the training documentation. From 184a7d60c902bb46b6f2ec3dd2aa1c1794a2413f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Sep 2021 01:31:39 -0700 Subject: [PATCH 25/34] Overhaul of markup-syntax.md. This got lost when I did a rebase. Add glossary term "fence" --- docs/contributing/markup-syntax.md | 317 +++++++++++++++++------------ docs/glossary.md | 21 ++ 2 files changed, 211 insertions(+), 127 deletions(-) diff --git a/docs/contributing/markup-syntax.md b/docs/contributing/markup-syntax.md index 44a29c030..7030f6458 100644 --- a/docs/contributing/markup-syntax.md +++ b/docs/contributing/markup-syntax.md @@ -1,200 +1,263 @@ --- html_meta: - "description": "Guide to Sphinx, MyST, and Markdown" - "keywords": "Sphinx, MyST, Markdown" + "description": "General Guide to Writing Documentation" + "keywords": "Documentation, Plone, Sphinx, MyST, reStructuredText, Markdown" --- -# Guide for Authors +# General Guide to Writing Documentation -## MyST, Markdown, Sphinx +This guide provides general help for writing documentation for Plone Trainings. + + +## MyST, reStructuredText, and Markdown We use [MyST, or Markedly Structured Text](https://myst-parser.readthedocs.io/en/latest/), a rich and extensible flavor of Markdown, for authoring training documentation. -Meta Tags -: You can improve the findability of a chapter in search engines by adding meta tags. +MyST extends {term}`Markdown` by incorporating all the features of {term}`reStructuredText` and {term}`Sphinx` and its extensions. +Contributors are welcome to use either Markdown or MyST syntax. - --- - html_meta: - "description": "directives and other examples in markdown / MySt" - "keywords": "Sphinx, MyST, markdown" - --- +MyST may be more familiar to reStructuredText authors. +MyST allows the use of a {term}`fence` and `{rst-eval}` to evaluate native reStructuredText. +This may be useful when Markdown does not provide sufficient flexibility, such as for `figure`. -Cross Reference: chapter -: Link to another chapter. -: We created an add-on in the last chapter {doc}`volto_custom_addon`. -Cross Reference: section -: Link to a section of a chapter +### MyST Syntax Reference -: create anchor - ``` - (volto-custom-addon-final-label)= - ``` - create link - ``` - Switch to section [Release a Volto add-on](/mastering-plone/volto_custom_addon.html#volto-custom-addon-final-label). - ``` - or +The following are frequently used snippets and examples. - ``` - Switch to section {ref}`Release a Volto add-on `. - ``` +```{seealso} -Image -: ```{figure} _static/volto_addon_accordion_display.png - :alt: Volto add-on volto-accordion-block - ``` +**Official MyST documentation** -: with caption: +- [The MyST Syntax Guide](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html) +- [MyST Syntax Reference](https://myst-parser.readthedocs.io/en/latest/syntax/reference.html) +``` - ```{figure} _static/volto_addon_accordion_display.png - :alt: Volto add-on volto-accordion-block - Accordion Block - ``` +#### Targets and Cross-Referencing -: with zoom: +```{seealso} +[The MyST Syntax Guide > Targets and Cross-Referencing](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#targets-and-cross-referencing) +``` - ```{figure} _static/volto_addon_accordion_display.png - :alt: Volto add-on volto-accordion-block - :width: 100% - ``` +##### Link to a Chapter or Page -Code Block -: example code `Python` +```md +We created an add-on in the last chapter {doc}`/mastering-plone/volto_custom_addon`. +``` - ```{code-block} python - :lineno-start: 10 - :emphasize-lines: 1, 3 +We created an add-on in the last chapter {doc}`/mastering-plone/volto_custom_addon`. - a = 2 - print('my 1st line') - print(f'my {a}nd line') - ``` -: is rendered as: +(markup-syntax-link-heading-label)= -```{code-block} python -:lineno-start: 10 -:emphasize-lines: 1, 3 +##### Link to a Heading -a = 2 -print('my 1st line') -print(f'my {a}nd line') +```md +(markup-syntax-hello-heading-label)= + +###### Hello Heading + +Read the section {ref}`markup-syntax-link-heading-label`. ``` -The lexers check the syntax. Be sure to provide valid code for a correct highlighting. +(markup-syntax-hello-heading-label)= + +###### Hello Heading + +Read the section {ref}`markup-syntax-hello-heading-label`. + -jsx does not allow a tick `'` in nodes. +##### Link to an Arbitrary Location -```jsx -import React from 'react'; +```md +(example-target-label)= -const TalkView = props => { - return
I'm the TalkView component!
; -}; +I have an HTML anchor above me. -export default TalkView; +Click the link to visit {ref}`my text `. ``` -```jsx -import React from 'react'; +(example-target-label)= -const TalkView = props => { - return
I am the TalkView component!
; -}; +I have an HTML anchor above me. -export default TalkView; +Click the link to visit {ref}`my text `. + + +##### Link to External Page + +```md +Use [Shimmer](http://example.com) for cleaner whiter teeth. ``` +Use [Shimmer](http://example.com) for cleaner whiter teeth. + + +##### Images and Figures + +[Figures](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure) allow a caption and legend, whereas [images](https://docutils.sourceforge.io/docs/ref/rst/directives.html#images) do not. + +Use `image` for anything but diagrams. -Code Snippet Expandable -: Solutions of Exercises +Use `figure` for diagrams. - Be aware of the nested directives! Increase outer back ticks! +Images and figures should always include `alt` text. - ````{admonition} Complete code for ReactJS component - :class: toggle +From [Web Accessibility In Mind (WebAIM)](https://webaim.org/techniques/alttext/): - Here's my code snippet +> Alternative text serves several functions: +> - It is read by screen readers in place of images allowing the content and function of the image to be accessible to those with visual or certain cognitive disabilities. +> - It is displayed in place of the image in browsers if the image file is not loaded or when the user has chosen not to view images. +> - It provides a semantic meaning and description to images which can be read by search engines or be used to later determine the content of the image from page context alone. + +Accessibility is part of the [Plone brand and identity](https://plone.org/accessibility). + +````md +```{image} /_static/standards.png +:alt: XKCD "Standards" comic strip +``` +```` + +```{image} /_static/standards.png +:alt: XKCD "Standards" comic strip +``` - Maecenas sed diam eget risus varius blandit sit amet non magna. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Nullam quis risus eget urna mollis ornare vel eu leo. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Nulla vitae elit libero, a pharetra augue. +````md +```{eval-rst} +.. figure:: /_static/voting_flowchart.png + :alt: Voting flowchart + + This is a caption in a single paragraph. + + This is a legend, which consists of all elements after the caption. + It can include a table. + + ====== ======= + Symbol Meaning + ====== ======= + ⃞ Object + ⬭ View + ➞ Flow + ====== ======= +``` +```` +```{eval-rst} +.. figure:: /_static/voting_flowchart.png + :alt: Voting flowchart + + This is a caption in a single paragraph. + + This is a legend, which consists of all elements after the caption. + It can include a table. + + ====== ======= + Symbol Meaning + ====== ======= + ⃞ Object + ⬭ View + ➞ Flow + ====== ======= +``` - ```{code-block} jsx - :linenos: true - import React, { useState } from 'react'; - ``` - ```` +##### Code Block -````{admonition} Complete code for ReactJS component -:class: toggle +A Python code snippet without reStructuredText options, using a simple fence. -Here's my code snippet +````md +```python +a = 2 +print("my 1st line") +print(f"my {a}nd line") +``` +```` -Maecenas sed diam eget risus varius blandit sit amet non magna. Aenean eu leo quam. Pellentesque ornare sem lacinia quam venenatis vestibulum. Nullam quis risus eget urna mollis ornare vel eu leo. Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Praesent commodo cursus magna, vel scelerisque nisl consectetur et. Etiam porta sem malesuada magna mollis euismod. Nulla vitae elit libero, a pharetra augue. +```python +a = 2 +print("my 1st line") +print(f"my {a}nd line") +``` +A Python code snippet with reStructuredText options, using a fence with the parsed reStructuredText directive `code-block`. -```{code-block} jsx -:linenos: true +````md +```{code-block} python +:lineno-start: 10 +:emphasize-lines: 1, 3 -import React, { useState } from 'react'; +a = 2 +print("my 1st line") +print(f"my {a}nd line") ``` ```` -Notes and other highlighted blocks -: To highlight a block you can use the directives `note`, `warning`, `attention`, `caution`, `danger`, `error`, `hint`, `important`, `tip` +```{code-block} python +:lineno-start: 10 +:emphasize-lines: 1, 3 + +a = 2 +print("my 1st line") +print(f"my {a}nd line") +``` + +##### Escape literal backticks inline + +```md +This is MyST syntax for term ``{term}`React` `` +``` - ```{tip} - You can find the list with the global Semantic UI variables available in `omelette/theme/themes/default/globals/site.variables`. - ``` +This is MyST syntax for term ``{term}`React` `` + + + +##### Glossary terms + +Add a term to the {doc}`glossary`, located at {file}`/glossary.md`. + +```md +React + [React](https://reactjs.org/) is a JavaScript library for building user interfaces. + Volto, the frontend for Plone 6, uses React. +``` +Reference a term in the {doc}`glossary`. -```{tip} -You can find the list with the global Semantic UI variables available in `omelette/theme/themes/default/globals/site.variables`. +```md +Using {term}`React` makes frontends fun again! ``` -Glossary -: Reference glossary terms +Using {term}`React` makes frontends fun again! - To reference terms in your glossary, use the `{term} role`. - For example, ``{term}`ReactJS` `` becomes a reference to term {term}`ReactJS`. -: Add glossary term - Add your term to `/glossary.md` +## Abridged Plone Documentation Styleguide -Modes -: The training is rendered using Sphinx and builds in two flavors: +Guides should be informational, but friendly. - default - : The verbose version used for the online documentation and for the trainer. - : Build it in Sphinx with `make html` or use the online version [training.plone.org](https://training.plone.org). See {doc}`/contributing/setup-author`. +Address the reader by using "you" instead of "the user". - presentation - : An abbreviated version used for the projector during a training. - : It should use more bullet points than verbose text. - : Build it in Sphinx with `make presentation`. +Avoid contractions, and spell out the words. +For example, use "do not" instead of "don't". - With directive `{only} not presentation` you can control - that a block is used for the presentation version only. +Please do not follow PEP8 maximum line length standard. +Documentation is narrative text and images, not Python code. - ```{only} not presentation - You can extend the functionality of your Dexterity object by writing an adapter that adapts your dexterity object to add another feature or aspect. +Use one sentence per line. +Keep sentences short and understandable. +This will greatly improve the editing and maintenance of your documentation. - But if you want to use this adapter, you must somehow know that an object implements that. - Also, adding more fields to an object would not be easy with such an approach. - ``` - To hide a block from the presentation version use `{only} not presentation`. +## General Documentation Writing References - ```{only} presentation - You can extend the functionality of your Dexterity object by writing an adapter that adapts your dexterity object to add another feature or aspect. +- [Write the Docs - Documentation Guide](https://www.writethedocs.org/guide/) +- [A Guide to Em Dashes, En Dashes, and Hyphens](https://www.merriam-webster.com/words-at-play/em-dash-en-dash-how-to-use) - But if you want to use this adapter, you must somehow know that an object implements that. - Also, adding more fields to an object would not be easy with such an approach. - ``` - Content without a directive will be included in both versions. +### English grammar, spelling, punctuation, and syntax +Because it is difficult to automate good English grammar and syntax, we do not strictly enforce it. +We also understand that contributors might not be fluent in English. +We encourage contributors to make a reasonable effort, and to seek help from community members who are fluent in English. +Please ask! diff --git a/docs/glossary.md b/docs/glossary.md index 9fc535933..e6350a10b 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -219,4 +219,25 @@ MyST Markdown [Markdown](https://daringfireball.net/projects/markdown/) is a text-to-HTML conversion tool for web writers. + +fence + A method to extend basic MyST syntax. + You can define a directive with backticks (`` ` ``) followed by a reStructuredText directive in curly brackets (`{}`), and a matching number of closing backticks. + You can also nest fences by increasing the number of backticks. + + `````md + ````{warning} + There be dragons! + ```{important} + Dragons have feelings, too! + ``` + ```` + ````` + + ````{warning} + There be dragons! + ```{important} + Dragons have feelings, too! + ``` + ```` ``` From ea9c2e6d0d4228863cdcb19ede6fd1c76d076f30 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Sep 2021 01:35:16 -0700 Subject: [PATCH 26/34] Rename and refactor markup-syntax to writing-docs-guide --- docs/contributing/authors.md | 4 ++-- docs/contributing/index.md | 6 +++--- .../{markup-syntax.md => writing-docs-guide.md} | 10 +++++----- 3 files changed, 10 insertions(+), 10 deletions(-) rename docs/contributing/{markup-syntax.md => writing-docs-guide.md} (96%) diff --git a/docs/contributing/authors.md b/docs/contributing/authors.md index 8fdd660c2..80413f99c 100644 --- a/docs/contributing/authors.md +++ b/docs/contributing/authors.md @@ -10,7 +10,7 @@ html_meta: This guide is for authors of Training documentation. It covers configuring quality checks and syntax for writing markup that is of particular interest to authors. -For general markup syntax, see {doc}`markup-syntax`. +For general markup syntax, see {doc}`writing-docs-guide`. (authors-html-meta-data-label)= @@ -133,7 +133,7 @@ We strive for high quality documentation, setting the following minimum standard ### Markup syntax must be valid -See both the specific markup syntax above and general markup in {doc}`markup-syntax`. +See both the specific markup syntax above and general markup in {doc}`writing-docs-guide`. To validate markup, run the following command. diff --git a/docs/contributing/index.md b/docs/contributing/index.md index a57636eec..bda936106 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -69,9 +69,9 @@ Contributors to the Training docs may perform one or many roles. - **Plone users and developers** use this documentation because it is accurate and actively maintained. People in these roles typically contribute minor corrections. - They should read {doc}`setup-build` and {doc}`markup-syntax`. + They should read {doc}`setup-build` and {doc}`writing-docs-guide`. - **Authors** create the Training documentation. - They should read {doc}`setup-build` and {doc}`markup-syntax`. + They should read {doc}`setup-build` and {doc}`writing-docs-guide`. They should also read {doc}`authors` for guidance and tips for writing good Training documentation. - **Trainers** should read {doc}`setup-build`, {doc}`trainers`, and the trainings in {doc}`/plone_training_config/instructions` and {doc}`/teachers-training/index`. These documents help trainers prepare for a successful training experience. @@ -102,7 +102,7 @@ hidden: true --- setup-build -markup-syntax +writing-docs-guide trainers authors ``` diff --git a/docs/contributing/markup-syntax.md b/docs/contributing/writing-docs-guide.md similarity index 96% rename from docs/contributing/markup-syntax.md rename to docs/contributing/writing-docs-guide.md index 7030f6458..503c542d6 100644 --- a/docs/contributing/markup-syntax.md +++ b/docs/contributing/writing-docs-guide.md @@ -49,23 +49,23 @@ We created an add-on in the last chapter {doc}`/mastering-plone/volto_custom_add We created an add-on in the last chapter {doc}`/mastering-plone/volto_custom_addon`. -(markup-syntax-link-heading-label)= +(writing-docs-guide-link-heading-label)= ##### Link to a Heading ```md -(markup-syntax-hello-heading-label)= +(writing-docs-guide-hello-heading-label)= ###### Hello Heading -Read the section {ref}`markup-syntax-link-heading-label`. +Read the section {ref}`writing-docs-guide-link-heading-label`. ``` -(markup-syntax-hello-heading-label)= +(writing-docs-guide-hello-heading-label)= ###### Hello Heading -Read the section {ref}`markup-syntax-hello-heading-label`. +Read the section {ref}`writing-docs-guide-hello-heading-label`. ##### Link to an Arbitrary Location From 8f8fe69d301db00f21dff51cc7847455d415d444 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Sep 2021 01:40:20 -0700 Subject: [PATCH 27/34] Rename and refactor teachers-training to teaching --- docs/contributing/index.md | 2 +- docs/contributing/trainers.md | 4 ++-- docs/{teachers-training => teaching}/after.md | 0 docs/{teachers-training => teaching}/before.md | 0 docs/{teachers-training => teaching}/during.md | 0 docs/{teachers-training => teaching}/index.md | 0 docs/{teachers-training => teaching}/theory.md | 0 7 files changed, 3 insertions(+), 3 deletions(-) rename docs/{teachers-training => teaching}/after.md (100%) rename docs/{teachers-training => teaching}/before.md (100%) rename docs/{teachers-training => teaching}/during.md (100%) rename docs/{teachers-training => teaching}/index.md (100%) rename docs/{teachers-training => teaching}/theory.md (100%) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index bda936106..0fbe39905 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -73,7 +73,7 @@ Contributors to the Training docs may perform one or many roles. - **Authors** create the Training documentation. They should read {doc}`setup-build` and {doc}`writing-docs-guide`. They should also read {doc}`authors` for guidance and tips for writing good Training documentation. -- **Trainers** should read {doc}`setup-build`, {doc}`trainers`, and the trainings in {doc}`/plone_training_config/instructions` and {doc}`/teachers-training/index`. +- **Trainers** should read {doc}`setup-build`, {doc}`trainers`, and the trainings in {doc}`/plone_training_config/instructions` and {doc}`/teaching/index`. These documents help trainers prepare for a successful training experience. diff --git a/docs/contributing/trainers.md b/docs/contributing/trainers.md index 6db2f88f6..05f53b212 100644 --- a/docs/contributing/trainers.md +++ b/docs/contributing/trainers.md @@ -11,7 +11,7 @@ html_meta: Feel free to organize a training yourself. Please be so kind to contribute any bug fixes or enhancements you made to the documentation for your training. -Trainers should read {doc}`setup-build` and the trainings in {doc}`/plone_training_config/instructions` and {doc}`/teachers-training/index`. +Trainers should read {doc}`setup-build` and the trainings in {doc}`/plone_training_config/instructions` and {doc}`/teaching/index`. These documents help trainers prepare for a successful training experience. @@ -55,4 +55,4 @@ We really want this material to be used, re-used, expanded, and improved by Plon These chapters don't contain any Plone specific advice. There's background, theory, check lists, and tips for anyone trying to teach technical subjects. -{doc}`/teachers-training/index` +{doc}`/teaching/index` diff --git a/docs/teachers-training/after.md b/docs/teaching/after.md similarity index 100% rename from docs/teachers-training/after.md rename to docs/teaching/after.md diff --git a/docs/teachers-training/before.md b/docs/teaching/before.md similarity index 100% rename from docs/teachers-training/before.md rename to docs/teaching/before.md diff --git a/docs/teachers-training/during.md b/docs/teaching/during.md similarity index 100% rename from docs/teachers-training/during.md rename to docs/teaching/during.md diff --git a/docs/teachers-training/index.md b/docs/teaching/index.md similarity index 100% rename from docs/teachers-training/index.md rename to docs/teaching/index.md diff --git a/docs/teachers-training/theory.md b/docs/teaching/theory.md similarity index 100% rename from docs/teachers-training/theory.md rename to docs/teaching/theory.md From f4c8763721b0c897a5baab688fe16e25a021388d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Sep 2021 01:54:58 -0700 Subject: [PATCH 28/34] Remove redundant sections and add references to authoritative sources --- docs/teaching/index.md | 27 ++++++++++----------------- 1 file changed, 10 insertions(+), 17 deletions(-) diff --git a/docs/teaching/index.md b/docs/teaching/index.md index 71e978dd6..d93f4346b 100644 --- a/docs/teaching/index.md +++ b/docs/teaching/index.md @@ -1,34 +1,27 @@ -(about-use-label)= +(teaching-index-label)= # Teaching +This section covers all that trainers need to know when teaching Plone Trainings. + +Trainers should read {doc}`/contributing/setup-build` and the trainings in {doc}`/plone_training_config/instructions`. +These documents help trainers prepare for a successful training experience. + + ## Using the documentation for a training Feel free to organize a training yourself. Please be so kind to contribute any bug fixes or enhancements you made to the documentation for your training: {doc}`/contributing/index` + ## License The Mastering Plone Training is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). -## Complete Mode and compact Presentation Mode - -The training is rendered using Sphinx and builds in two flavors: - -default -: The verbose version used for the online documentation and for the trainer. -: Build it in Sphinx with `make html` or use the online version. - -presentation -: An abbreviated version used for the projector during a training. -: It should use more bullet points than verbose text. -: Build it in Sphinx with `make presentation`. - - -## Setup Environment +## Available documentation builds -See {doc}`/contributing/setup-author` for instructions on how to set up the training documentation locally. +See {ref}`setup-build-available-documentation-builds-label`. (train-the-trainer-label)= From ac21ab5dc916c3e5186ed92d1875a3c25b4c7f74 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Sep 2021 02:11:13 -0700 Subject: [PATCH 29/34] Use modern placeholder image services that don't timeout and cause linkcheck to fail --- docs/mastering-plone-5/thirdparty_behaviors.md | 2 +- docs/mastering-plone/thirdparty_behaviors.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/mastering-plone-5/thirdparty_behaviors.md b/docs/mastering-plone-5/thirdparty_behaviors.md index 00495a1a9..6a762bcc1 100644 --- a/docs/mastering-plone-5/thirdparty_behaviors.md +++ b/docs/mastering-plone-5/thirdparty_behaviors.md @@ -50,6 +50,6 @@ You need to run {file}`./bin/buildout` again for these changes to take effect. - Install the add-on - Create a new dexterity content type `Banner` with **only** the behavior `Banner` enabled. - Create a folder called `banners` -- Add two banners into that folder using images taken from or +- Add two banners into that folder using images taken from or - Add the Behavior `Slider` to the default content type `Page (Document)` - Edit the front-page and link to the new banners. diff --git a/docs/mastering-plone/thirdparty_behaviors.md b/docs/mastering-plone/thirdparty_behaviors.md index 6e63dfd12..ef28bcb33 100644 --- a/docs/mastering-plone/thirdparty_behaviors.md +++ b/docs/mastering-plone/thirdparty_behaviors.md @@ -56,6 +56,6 @@ You need to run {file}`./bin/buildout` again for these changes to take effect. - Install the add-on - Create a new dexterity content type `Banner` with **only** the behavior `Banner` enabled. - Create a folder called `banners` -- Add two banners into that folder using images taken from or +- Add two banners into that folder using images taken from or - Add the Behavior `Slider` to the default content type `Page (Document)` - Edit the front-page and link to the new banners. From 3321d44056697c497b5ff8edc26c14be88f63ee4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 14 Sep 2021 06:04:18 -0700 Subject: [PATCH 30/34] Expand section on syntax highlighting and lexers --- docs/contributing/authors.md | 46 ++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/contributing/authors.md b/docs/contributing/authors.md index 80413f99c..22ccf6927 100644 --- a/docs/contributing/authors.md +++ b/docs/contributing/authors.md @@ -217,18 +217,33 @@ Please do not be "that person". ### Syntax highlighting -Sample code blocks perform syntax highlighting through Pygments. +Pygments provides syntax highlighting in Sphinx. + +When including code snippets, you should specify the language. Authors must use a proper [Pygments lexer](https://pygments.org/docs/lexers/) and not generate warnings. +The snippet must be valid syntax for the language you specify, else it will not be highlighted properly. Avoid adding comments to code snippets, unless you use valid comment syntax for that language. -JSON does not allow comments. +For example, JSON does not allow comments. Do not indicate elided or omitted code with ellipses (`...` or `…`). These are almost never valid syntax and will cause syntax highlighting to fail for the code block. + +#### Choosing a Lexer + Some lexers are less than perfect. If your code block does not highlight well, then consider specifying a less ambitious lexer, such as `text`. +Use `shell` for commands to be issued in a terminal session. +Do not include shell prompts. +This will make commands easy to copy and paste for readers. + +Use `console` for output of a shell session. +If you have a mix of a shell command and its output, then use `console`. + +If `xml` does not work well, then try `html`. + `jsx` has a complex syntax that is difficult to parse. We have high hopes for the project [`jsx-lexer`](https://github.com/fcurella/jsx-lexer). We include it in our `requirements.txt` file. @@ -236,6 +251,29 @@ Please contribute to its further development. The lexers `html+ng2`, `scss`, `http`, `less` are also suboptimal and particular. +If no other lexer works well, then fall back to `text`. +At least then the build will succeed without warnings, although syntax highlighting for such snippets will not appear. + + +#### Validate the Lexer + +Always build the page to validate syntax. +Your own training should not be merged into the larger Training docs if there are any Sphinx warnings. +The Sphinx console will display any warnings, such as the following. + +```console +/Plone/training/voltohandson/introtoblocks.md:55: WARNING: Could not lex literal_block as "jsx". Highlighting skipped. +``` + +The above warning indicates that the syntax is not valid. +Common mistakes include: + +- Using `...` or `…` to indicate omitted code. + It is preferable to never use ellipses. + If you must do that, comment it out using the language's comment syntax. +- Using comments in JSON. +- A previous code block bleeds through to the next due to invalid MyST syntax. + To validate code block syntax, run the following command. ```shell @@ -243,6 +281,10 @@ make html ``` An [online demo of all lexers that Pygments supports](https://pygments.org/demo/) may be helpful to test out your code blocks and snippets for syntax highlighting. +You can also use the [`pygmentize`](https://pygments.org/docs/cmdline/) binary. + +When using the online lexer, if any red-bordered rectangles appear, then the lexer for Pygments interprets your snippet as not valid. +You can search the [Pygments issue tracker](https://github.com/pygments/pygments/search) for possible solutions, or submit a pull request to enhance the lexer. ## Synchronize the Browser While Editing From 1ea7a22522e1cc1cd4dd39cc14660f1e3fccb322 Mon Sep 17 00:00:00 2001 From: ksuess Date: Wed, 15 Sep 2021 13:01:16 +0200 Subject: [PATCH 31/34] Fix links to /teaching/ --- docs/index.md | 6 +++--- docs/mastering-plone-5/about_mastering.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/index.md b/docs/index.md index 11ef2aa11..5d749846a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,7 +33,7 @@ advanced-python/index glossary contributing/index -teachers-training/index +teaching/index ``` @@ -127,8 +127,8 @@ teachers-training/index {doc}`contributing/index` -: Contributing to the training documentation +: All about contributing to documentation -{doc}`teachers-training/index` +{doc}`teaching/index` : How To Give Technical Trainings diff --git a/docs/mastering-plone-5/about_mastering.md b/docs/mastering-plone-5/about_mastering.md index 463161dbd..4ca7181c9 100644 --- a/docs/mastering-plone-5/about_mastering.md +++ b/docs/mastering-plone-5/about_mastering.md @@ -302,7 +302,7 @@ We really want this material to be used, re-used, expanded, and improved by Plon These chapters don't contain any Plone specific advice. There's background, theory, check lists, and tips for anyone trying to teach technical subjects. -{doc}`../teachers-training/index` +{doc}`../teaching/index` (plone5-about-contribute-label)= From f9e94b892cb29c51f08c8437be3df23094290940 Mon Sep 17 00:00:00 2001 From: ksuess Date: Wed, 15 Sep 2021 13:06:03 +0200 Subject: [PATCH 32/34] Hide toc from landing page --- docs/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.md b/docs/index.md index 5d749846a..5e807b436 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,6 +5,7 @@ A collection of trainings developed and created by the Plone Community. ```{toctree} :caption: Training Overview :maxdepth: 2 +:hidden: true mastering-plone/index mastering-plone-5/index @@ -30,6 +31,7 @@ advanced-python/index ```{toctree} :caption: Plone Trainings :maxdepth: 1 +:hidden: true glossary contributing/index From fd341bff595ff2242665b2f13a08a23bf4a2cf35 Mon Sep 17 00:00:00 2001 From: ksuess Date: Wed, 15 Sep 2021 13:27:06 +0200 Subject: [PATCH 33/34] Remove redundant info about contributing and teaching from mastering-plone-5 --- docs/mastering-plone-5/about_mastering.md | 213 +--------------------- 1 file changed, 7 insertions(+), 206 deletions(-) diff --git a/docs/mastering-plone-5/about_mastering.md b/docs/mastering-plone-5/about_mastering.md index 4ca7181c9..711ae031d 100644 --- a/docs/mastering-plone-5/about_mastering.md +++ b/docs/mastering-plone-5/about_mastering.md @@ -110,220 +110,21 @@ Leonardo Caballero Currently serving the Plone Board as a Plone Ambassador, Leonardo has also served as an Advisory Board member and has spoken at or helped organize Plone and open-source events throughout South America. -(plone5-about-use-label)= - -## Using the documentation for a training - -Feel free to organize a training yourself. -Please be so kind to contribute any bug fixes or enhancements you made to the documentation for your training. - -The training is rendered using Sphinx and builds in two flavors: - -default - -: The verbose version used for the online documentation and for the trainer. - Build it in Sphinx with `make html` or use the online version. - -presentation - -: An abbreviated version used for the projector during a training. - It should use more bullet points than verbose text. - Build it in Sphinx with `make presentation`. - -```{note} -By prefixing an indented block of text or code with `.. only:: presentation` you can control -that this block is used for the presentation version only. - -To hide a block from the presentation version use `.. only:: not presentation` - -Content without a prefix will be included in both versions. -``` - -### The readthedocs theme - -We slightly tweaked the [Read the Docs Theme](https://github.com/readthedocs/sphinx_rtd_theme) -in `_static/custom.css` so that it works better with projectors: - -- We start hiding the navigation bar much earlier so that it does not interfere with the text. -- We enlarge the default width of the content-area. - -### Exercises - -Some additional JavaScript shows hidden solutions for exercises by clicking. - -Prepend the solution with this markup: - -``` -.. admonition:: Solution - :class: toggle -``` - -Here is a full example - -```rst -Exercise 1 -^^^^^^^^^^ - -Your mission, should you choose to accept it... - -.. admonition:: Solution - :class: toggle - - To save the world with only seconds to spare do the following: - - .. code-block:: python - - from plone import api -``` - -It will be rendered like this: - -#### Exercise 1 - -Your mission, should you choose to accept it... - -````{admonition} Solution -:class: toggle - -To save the world with only seconds to spare do the following: - -```python -from plone import api -``` -```` - -## Building the documentation locally - -### Dependencies - -Please make sure that you have [Enchant](https://abiword.github.io/enchant/) installed. This is needed for spell-checking. - -Install Enchant on macOS: - -```shell -brew install enchant -``` -Install Enchant on Ubuntu: - -```shell -sudo apt-get install enchant -``` - -To build the documentation follow these steps: - -```shell -git clone https://github.com/plone/training.git -cd training -python -m venv . -source bin/activate -``` - -Now install dependencies and build. - -```shell -pip install -r requirements.txt -make html -``` - -You can now open the output from `_build/html/index.html`. -To build the presentation version use `make presentation` instead of `make html`. - -You can open the presentation at `presentation/index.html`. - -## Build new - -```shell -git clone https://github.com/plone/training.git -cd training -python -m venv . -source bin/activate -pip install -r requirements.txt -make html -``` - -Now you can open documentation with your web-bowser. - -If you use macOS you can do: - -```shell -open _build/html/index.html -``` - -In the case of Linux, Ubuntu for example you can do: - -```shell -firefox _build/html/index.html -``` - -```{note} -If you do not use Firefox but Chrome, please replace firefox with google-chrome e.g -``` - -```shell -google-chrome _build/html/index.html -``` - -### Update existing - -```shell -$ git pull -$ source bin/activate -$ make html -$ open _build/html/index.html -``` - -### Technical set up to do before a training (as a trainer) - -- Prepare a mail server for the user registration mail (See {ref}`plone5-features-mailserver-label`) -- If you do only a part of the training (Advanced) prepare a database with the steps of the previous sections. Be aware that the file- and blobstorage in the Vagrant box is here: /home/vagrant/var/ (not at the buildout path /vagrant/buildout/) - -### Upgrade the vagrant and buildout to a new Plone-version - -- In change [buildout.cfg](https://github.com/collective/training_buildout/blob/master/buildout.cfg) to extend from the new `versions.cfg` on -- Check if we should to update any versions in -- Commit and push the changes to the training_buildout -- Modify the vagrant-setup by modifying {file}`plone_training_config/manifests/plone.pp`. Set the new Plone-version as `$plone_version` in line 3. -- Test the vagrant-setup it by creating a new vagrant-box using the new config. -- Create a new zip-file of all files in `plone_training_config` and move it to `_static`: +(plone5-about-licence-label)= -```shell -cd plone_training_config -zip -r ../_static/plone_training_config.zip * -``` +## License -- Commit and push the changes to +The Mastering Plone Training is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). -## Train the trainer -If you are a trainer there is a special mini training about giving technical trainings. -We really want this material to be used, re-used, expanded, and improved by Plone trainers world wide. +(plone5-about-use-label)= -These chapters don't contain any Plone specific advice. -There's background, theory, check lists, and tips for anyone trying to teach technical subjects. +## Using the documentation for a training -{doc}`../teaching/index` +See the information for {doc}`teaching`. -(plone5-about-contribute-label)= ## Contributing -Everyone is **very welcome** to contribute. -Minor bug fixes can be pushed directly in the [repository](https://github.com/plone/training), -bigger changes should made as [pull-requests](https://github.com/plone/training/pulls/) and discussed previously in tickets. - -(plone5-about-licence-label)= - -## License - -The Mastering Plone Training is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). - -Make sure you have filled out a [Contributor Agreement](https://plone.org/foundation/contributors-agreement). - -If you haven't filled out a Contributor Agreement, you can still contribute. -Contact the Documentation team, for instance via the [mailinglist](https://sourceforge.net/p/plone/mailman/plone-docs/) -or directly send a mail to - -Basically, all we need is your written confirmation that you are agreeing your contribution can be under Creative Commons. - -You can also add in a comment with your pull request "I, \, agree to have this published under Creative Commons 4.0 International BY". +Everyone is **very welcome** to contribute. See the information for {doc}`contributing`. From 5d9fffde40f665eb4bebf8d56cb6e69c3a19bb13 Mon Sep 17 00:00:00 2001 From: ksuess Date: Wed, 15 Sep 2021 13:28:44 +0200 Subject: [PATCH 34/34] Complement info about teaching in "about mastering plone training" --- docs/mastering-plone/about_mastering.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/mastering-plone/about_mastering.md b/docs/mastering-plone/about_mastering.md index ccb1da81e..aaf03e482 100644 --- a/docs/mastering-plone/about_mastering.md +++ b/docs/mastering-plone/about_mastering.md @@ -126,6 +126,12 @@ Leonardo Caballero The Mastering Plone Training is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). + +## Using the documentation for a training + +See the information for {doc}`teaching`. + + ## Contributing You are welcome to contribute. See {doc}`/contributing/index` for more info.