From 664ca91c2eb96de2d88d55c87f35db7f030a7f0e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 23 Nov 2024 16:11:08 -0800 Subject: [PATCH] Remove cruft and update contribute to documentation to current standards (#1788) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Remove cruft and update contribute to documentation to current standards - Move update git submodules to Administrators guide from index.md - Update Vale instructions with latest release - Use linkcheckbroken to check links instead of linkcheck - Add instructions for how to ignore links - Add note admonition about suboptimal lexers - Improve usage of `html_meta` - Add Diátrix Framework description - Overhaul index.md to better direct readers to the right starting point - Purge Contributor roles - Remove redundant Documentation quality requirements - Simplify processes for how to contribute via GitHub website and local editor - Update make commands to most frequently used, with instructions for all commands - Add glossary terms * Add MyST-Markdown VSCode Extension --- .../contributing/github-navigation.png | Bin 0 -> 9025 bytes docs/_static/github-navigation.png | Bin 11221 -> 0 bytes docs/contributing/documentation/admins.md | 78 ++++++- docs/contributing/documentation/authors.md | 159 +++++++++---- docs/contributing/documentation/index.md | 211 +++++++----------- .../documentation/myst-reference.md | 2 +- .../contributing/documentation/setup-build.md | 73 +++--- .../documentation/themes-and-extensions.md | 3 +- docs/glossary.md | 7 + 9 files changed, 325 insertions(+), 208 deletions(-) create mode 100644 docs/_static/contributing/github-navigation.png delete mode 100644 docs/_static/github-navigation.png diff --git a/docs/_static/contributing/github-navigation.png b/docs/_static/contributing/github-navigation.png new file mode 100644 index 0000000000000000000000000000000000000000..6c3da925edbf8778416216e4c4e2a5ff2035d2b7 GIT binary patch literal 9025 zcmch-byOVR(k?u>LvV+|A!u+JU~mgga2wp+U4n-&c(B0W1b6q~2^N9|_rVh!0+-); z&v)LlzWe{}wW@b@RXtU`tJmt@{dC7^s43uJQeXlA030PnS*@3`_(cNIQD64=tL&Ws z0D^(NjEshoj0{l2!_~&#$r=D)O|~>Qw@~6>9fd&5%}2kpvtfGpYQ@HW&@vD0@B0oM z29BHen?pYt8*h-k+Cb7702FEVw>n~f0NyunjaCuYs)↰=?{7HUxr?z0d;@V)Kw8t_YPF7#^q% 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 literal 0 HcmV?d00001 diff --git a/docs/_static/github-navigation.png b/docs/_static/github-navigation.png deleted file mode 100644 index ef6f90d1c79b880291b47c07b57213385333f836..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 11221 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 MVsfI@!uo;#1Jp5IrvLx| diff --git a/docs/contributing/documentation/admins.md b/docs/contributing/documentation/admins.md index 9cbad1197..6fff60c1d 100644 --- a/docs/contributing/documentation/admins.md +++ b/docs/contributing/documentation/admins.md @@ -1,20 +1,27 @@ --- myst: html_meta: - "description": "Administrators' guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation." - "property=og:description": "Administrators' guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation." - "property=og:title": "Administrators Guide" + "description": "Administrators guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation." + "property=og:description": "Administrators guide to writing Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation." + "property=og:title": "Administrators guide" "keywords": "Plone, Documentation, automated deployments, hosting, automated testing, importing external packages, preview, build, pull request" --- (administrators-guide-label)= -# Administrators Guide +# Administrators guide This guide is for administrators of Plone Documentation. It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation. +## Deployments and hosting + +Plone Documentation is automatically deployed through GitHub Workflows. +The Plone Admin and Infrastructure Team maintains the processes and the servers where this documentation is hosted. +Some individual projects may also host their projects on Read the Docs. + + (administrators-import-docs-and-converting-to-myst-label)= ## Importing external docs and converting to MyST @@ -57,7 +64,7 @@ We did this for `plone.app.dexterity` and several other projects. ## Importing external docs with submodules To add an external package to Plone Documentation, we use git submodules. -We did this with Volto documentation. +We did this with `volto`, `plone.api`, and `plone.restapi` documentation. Your package must be available under the Plone GitHub organization. Inside the repository `plone/documentation`, add a git submodule that points to your project. @@ -199,3 +206,64 @@ build: # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition - exit 183; ``` + + +## Update git submodules + +Only members of the Plone Documentation Team should update git submodules from the primary repository `documentation`. + +1. Update all branches to pull in the latest changes to their primary branches. + Start from the root of the `documentation` project directory. + + ```shell + # documentation + git checkout 6.0 + git pull + # plone.api + cd submodules/plone.api + git checkout master + git pull + # plone.restapi + cd ../../submodules/plone.restapi + git checkout main + git pull + # plone.api + cd ../../submodules/volto + git checkout main + git pull + ``` + +1. Get the status of the submodules to determine whether you need to update the git submodules. + + ```shell + cd ../.. + git status + ``` + + If you see any of the submodules listed to add, then proceed to the next step, else you have nothing more to do. + +1. Update the submodule to point to the latest commit, and push your changes to the remote repository. + You can combine multiple submodules in a single command. + + ```shell + cd ../.. + + # for plone.api + git add submodules/plone.api + git commit -m "Update tip submodules/plone.api" + + # for plone.restapi + git add submodules/plone.restapi + git commit -m "Update tip submodules/plone.restapi" + + # for Volto + git add submodules/volto + git commit -m "Update tip submodules/volto" + + ## for all submodules + git add submodules/plone.api submodules/plone.restapi submodules/volto + git commit -m "Update tips submodules/plone.api submodules/plone.restapi submodules/volto" + + # finally push your changes + git push + ``` diff --git a/docs/contributing/documentation/authors.md b/docs/contributing/documentation/authors.md index 2a21fb2ac..c68c978be 100644 --- a/docs/contributing/documentation/authors.md +++ b/docs/contributing/documentation/authors.md @@ -18,13 +18,23 @@ For general markup syntax, see {doc}`myst-reference`. ## Synchronize the browser while editing -Use `sphinx-autobuild` to view changes in the browser while you edit documentation. +The following shell command rebuilds documentation as you edit its files, with live reload in the browser. ```shell make livehtml ``` -You can open a browser at http://127.0.0.1:8000/ to preview the documentation. +The console will give you the URL to open in a web browser. +The URL may vary, according to its configuration in the repository's {file}`Makefile`. + +```console +[sphinx-autobuild] Serving on http://127.0.0.1:8050 +``` + + +## Editor tools + +- [MyST-Markdown VS Code Extension](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) (authors-quality-checks-label)= @@ -46,18 +56,37 @@ To validate markup, run the following command. make html ``` -Open `/_build/html/index.html` in a web browser. +The console will report any errors. +You should fix the errors for those pages that you edit. + + +### Override `html` build configuration options + +Sphinx supports overriding configuration options. +The following examples serve as tips for spotting mistakes in your documentation when you have too many errors or warnings. + +In Sphinx, you can use the `SPHINXOPTS` environment variable to set [configuration options](https://www.sphinx-doc.org/en/master/usage/configuration.html) of [`sphinx-build`](https://www.sphinx-doc.org/en/master/man/sphinx-build.html). +Syntax is in the following form. + +```shell +make SPHINXOPTS="OPTION VALUE" BUILDER +``` + +The following example shows how to clean then build a live HTML preview of the documentation while suppressing syntax highlighting failures. + +```shell +make SPHINXOPTS="-D suppress_warnings=['misc.highlighting_failure']" clean livehtml +``` (authors-english-label)= -### American English spelling, grammar, and syntax, and style guide +### Vale for American English spelling, grammar, and syntax, and style guide [Vale](https://vale.sh/) is a linter for narrative text. -It checks spelling, English grammar, and style guides. +It checks spelling, English grammar and syntax, and style guides. Plone uses American English. -Vale also provides English grammar and syntax checking, as well as a Style Guide. The Plone Documentation Team selected the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) for its ease of use—especially for non-native English readers and writers—and attention to non-technical audiences. To perform all these checks, run the following command. @@ -66,8 +95,9 @@ To perform all these checks, run the following command. make vale ``` -Because it is difficult to automate good American English grammar and syntax, we do not strictly enforce it. +Because it is difficult to automate good American English grammar and syntax, it is not strictly enforced. We also understand that contributors might not be fluent in English. +If you are more comfortable writing in your preferred language, then you may submit a pull request written in your language, and the Documentation Team will use translation tools to translate it to English. We encourage contributors to make a reasonable effort, and to request a review of their pull request from community members who are fluent in English to fix grammar and syntax. Please ask! @@ -82,14 +112,14 @@ See {ref}`authors-advanced-vale-usage-label` for details. #### Advanced Vale usage -To have Vale check only a specific file or directory of files, you can issue [Vale commands](https://vale.sh/manual/) with options in a shell session. -To allow this, you must either: +You can pass options to Vale in the `VALEOPTS` and `VALEFILES` environment variables. +In the following example, you can run Vale to display warnings or errors only, not suggestions, in the console on a single file. -- activate your Python virtual environment -- use the virtual environment path, such as `bin/vale` -- install Vale using operating system's package manager +```shell +make vale VALEOPTS="--minAlertLevel='warning'" VALEFILES="docs/index.md" +``` -The Vale `Makefile` command automatically installs Vale into your Python virtual environment—which is also created via any documentation `Makefile` commands—when you invoke it for the first time. +The command `make vale` automatically installs Vale into your Python virtual environment—which is also created via any documentation `Makefile` commands—when you invoke it for the first time. Vale has [integrations](https://vale.sh/docs/integrations/guide/) with various IDEs. Integration might require installing Vale using operating system's package manager. @@ -103,8 +133,11 @@ Plone configures Vale in three places: - {file}`.vale.ini` is Vale's configuration file. This file allows overriding rules or changing their severity. - {file}`Makefile` passes options to the `vale` command, such as the files Vale checks. -- Plone documentation uses a custom spelling dictionary, with accepted and rejected spellings in `styles/Vocab/Plone`. - Authors should add new words and proper names using correct casing to {file}`styles/Vocab/Plone/accept.txt`, sorted alphabetically and case-insensitive. +- Plone documentation uses a custom spelling dictionary, with accepted and rejected spellings in {file}`styles/config/vocabularies/Plone/`. + Authors should add new words and proper names using correct casing to {file}`styles/config/vocabularies/Plone/accept.txt`, sorted alphabetically and case-insensitive. + + If Vale does not reject a spelling that should be rejected, then you can add it to {file}`styles/config/vocabularies/Plone/reject.txt`. +- You can add additional spellings to accept or reject in their respective files inside the {file}`styles/config/vocabularies/Base/` folder. (authors-linkcheck-label)= @@ -113,34 +146,42 @@ Plone configures Vale in three places: ```{important} Before you add a link, consider whether you really need it for the documentation. -Avoid linking to blog posts because they rapidly succumb to bitrot. -It is preferred to copy the content from the source and add a link to the source as a reference through a `seealso` admonition or footnote, than to merely link to the source. +Avoid linking to blog posts because they rapidly succumb to bit rot. +It is preferable to copy the content from the source and add a link to the source as a reference through a `seealso` admonition, than to merely link to the source. ``` Valid links are enforced automatically through Sphinx's `linkcheck` builder. +To validate links, run the following command. + +```shell +make linkcheckbroken +``` + +Only broken links will show in the console output. +Open `/_build/linkcheck/output.txt` for a list of all links that were checked and their result. [Configuration of the `linkcheck` builder](https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder) is in {file}`Makefile` and {file}`docs/conf.py`. -`linkcheck_ignore` supports regular expression syntax. +When you add a link to the documentation, it must be a valid public URL without requiring authentication. -When authors add a link to the documentation, it must be a valid public URL without requiring authentication. +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. -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. +If it is not a valid link, or is private or local, then you must exclude it from `linkcheck`. +You can do so by wrapping it in single backticks in the page. ```{example} 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. +Alternatively, you can add it to the `linkcheck_ignore` list in {file}`conf.py`. +`linkcheck_ignore` supports regular expression syntax. -```shell -make linkcheck +```python +linkcheck_ignore = [ + r"http://0.0.0.0", +] ``` -Open `/_build/linkcheck/output.txt` for a list of broken links. - ```{danger} Please do not abuse `linkcheck_ignore`. @@ -167,8 +208,19 @@ 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. +````{note} +There are some known issues with syntax highlighting with the lexers for `jsx`, `less`, and `scss`. +Try your best to fix the code example. + +```{seealso} +- [WARNING: Lexing literal_block ... as "jsx" resulted in an error at token: "'". Retrying in relaxed mode.](https://github.com/pygments/pygments/issues/2816) +- [LESS lexer marks nested `.` and `h2` as invalid](https://github.com/pygments/pygments/issues/2817) +- [WARNING: Lexing literal_block ... as "scss" resulted in an error at token: '$'](https://github.com/pygments/pygments/issues/2818) +``` +```` + -#### Choosing a Lexer +#### Choose 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`. @@ -183,9 +235,6 @@ 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. -Please contribute to its further development. The lexers `html+ng2`, `scss`, `http`, `less` are also suboptimal and particular. @@ -204,15 +253,15 @@ The Sphinx console will display any warnings, such as the following. ``` The above warning indicates that the syntax is not valid. -Common mistakes include: +Common mistakes include the following. -- 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. +- 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. +To validate code block syntax of a page you edit, run the following command. ```shell make html @@ -230,7 +279,15 @@ You can search the [Pygments issue tracker](https://github.com/search?q=repo%3Ap ### HTML and Open Graph metadata All documents must have a `myst` topmatter key with an `html_meta` directive at the top of every page. -When rendered to HTML, it inserts `` tags for improved search engine results and nicer social media posts. + +When you create a new page, you can either copy an existing page that has the `html_meta` information, or you can create an empty file and run a `make` command to add a metadata section as shown. + +```shell +touch path-to-file/my-file.md +make html_meta +``` + +When rendered to HTML, the `html_meta` directive inserts `` tags for improved search engine results and nicer social media posts. Authors should include at least `description`, `property=og:description`, `property=og:title`, and `keywords` meta tags. The following is an example of `html_meta`. @@ -262,6 +319,17 @@ Additional {term}`Open Graph` metadata is implemented through the Sphinx extensi See the site-wide configuration in {file}`conf.py`. +## Diátaxis framework + +Plone Documentation uses the {term}`Diátaxis framework`, a systematic approach to technical documentation authoring. +Rather than attempt to organize documentation toward a specific role such as "developer", "user", or "administrator", the Diátaxis framework organizes documentation into the four categories of tutorials, how-to guides, explanation, and reference. +In this way, your title or role does not matter. +Instead, what you want to achieve matters. +By keeping each page focused on one category, readers can focus on getting work done, understanding, or experimenting. + +Although Plone 6 Documentation is not completely aligned with the Diátaxis framework, it is gradually moving toward it. + + ## Plone documentation styleguide We follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/). @@ -269,25 +337,23 @@ We follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/styl Key concepts from that guide include the following. - Documentation should be informational, but friendly. -- Address the reader by using "you" instead of "the user". -- Headings should be Sentence cased, not Title Cased. +- Address the reader by using "you" instead of "the user", or by using the collective "we" and "our". +- Headings should be "Sentence cased", not "Title Cased". The Plone Documentation Team adopted additional guidelines. - Use one sentence per line. Keep sentences short and understandable. This will greatly improve the editing and maintenance of your documentation. - -- Do not follow PEP8 maximum line length standard. +- Do not follow the PEP8 maximum line length standard. Documentation is narrative text and images, not Python code. - - Use dashes `-` in filenames and avoid underscores. - - Images should be no wider than 740 pixels to fit within the documentation's main view port. This avoids scaling and reducing legibility of images. To make that work in Volto, set your browser width to 1180 pixels. You will notice that the drag and trash icons for each block move inside the block from outside. - + + If you create images wider than 740 pixels, then you must use image display enhancement as described in {ref}`enhance-images-label`. - In user documentation, provide screenshots of each step where the interface changes. It is painstaking, but worth the effort. Provide sufficient detail of what each option is and does. @@ -295,6 +361,7 @@ The Plone Documentation Team adopted additional guidelines. ## General documentation writing references +- [Diátaxis framework](https://www.diataxis.fr/) - [Write the Docs - Documentation Guide](https://www.writethedocs.org/guide/) - [Creating effective technical documentation](https://developer.mozilla.org/en-US/blog/technical-writing/), Dipika Bhattacharya, Technical Writer at Mozilla Developer Network - [A Guide to Em Dashes, En Dashes, and Hyphens](https://www.merriam-webster.com/grammar/em-dash-en-dash-how-to-use) diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md index e63c36592..072fdc3e7 100644 --- a/docs/contributing/documentation/index.md +++ b/docs/contributing/documentation/index.md @@ -9,22 +9,43 @@ myst: (contributing-documentation-index-label)= -# Contributing to documentation +# Contribute to documentation -This document describes how to contribute to Plone Documentation. +This part of the documentation describes how to contribute to Plone Documentation. +Contributions to Plone Documentation are welcome. -Contributions to the Plone Documentation are welcome. - -```{seealso} -To set up and build the documentation locally, see {doc}`setup-build`. +```{contents} On this page +:local: ``` +## Choose your path + +{doc}`/contributing/first-time` +: First-time contributors to Plone and its documentation should read this first. + Fixing typographical errors and writing documentation is a relatively easy way to learn how to contribute to Plone. + +{doc}`setup-build` +: Start here if you have previously contributed to Plone. + This guide shows you how to set up and build your environment to contribute to documentation. + +{doc}`authors` +: This guide shows you how to run a live preview of documentation while you edit it, perform quality checks, choose a code syntax highlighting lexer, improve search engine results, and follow structure, organization, and styles in Plone Documentation. + +{doc}`myst-reference` +: This reference guide provides frequently used MyST markup code snippets that you can use while you write documentation. + +{doc}`themes-and-extensions` +: This reference guide describes the themes and extensions used in Plone Documentation, with links to their documentation and usage. + +{doc}`admins` +: This guide covers automated deployments, hosting, automated testing, previewing, and importing and converting external package documentation into Plone Documentation. + (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. +Before you contribute documentation, you must give permission to publish your contribution according to the license we use. You may give that permission in two ways. - Sign the [Plone Contributor Agreement](https://plone.org/foundation/contributors-agreement). @@ -38,112 +59,71 @@ The Plone Documentation is licensed under the [Creative Commons Attribution 4.0 A copy of the license is included in the root of this repository. -(contributing-roles-label)= - -## Contributor roles - -Contributors to the Plone Documentation 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}`myst-reference`. -- **Authors** create Plone Documentation. - They should read {doc}`setup-build` and {doc}`myst-reference`. - They should also read {doc}`authors` for guidance and tips for writing good technical documentation. - - -(contributing-quality-requirements-label)= - -## Documentation quality requirements +(documentation-repositories-label)= -We use GitHub Actions with every pull request to enforce Plone 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. +## Documentation repositories - -(contributing-manage-on-github-label)= - -## Making contributions on GitHub - -Contributions are managed through git repositories on GitHub. +Plone documentation consists of several repositories. - [`documentation`](https://github.com/plone/documentation) - [`plone.api`](https://github.com/plone/plone.api) - [`plone.restapi`](https://github.com/plone/plone.restapi) - [`volto`](https://github.com/plone/volto) -In the Plone organization, it is strongly recommended that you read {ref}`contributing-permission-to-publish-label` and take appropriate action. - -After your Plone Contributor Agreement has been approved, and you have been added to the Plone GitHub organization as a member of the [Developers](https://github.com/orgs/plone/teams/developers) team, we recommend that you follow our guidelines. - -1. 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 in the issue trackers of documented projects, and comment on them. - If an issue does not already exist for what you want to work on, then create a new issue in its issue tracker. - - 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. +[`documentation`](https://github.com/plone/documentation) is the primary repository. +When you {doc}`setup and build ` the documentation, it will automatically pull in the other repositories via git submodules. - ```{image} /_static/github-navigation.png - :alt: GitHub navigation menu - ``` - - You can use this menu to quickly navigate to the `documentation` source repository or open an issue. - Note that this navigation convenience is provided only for the `documentation` repository. +```{important} +We currently use the branches `plone/documentation@6.0`, `plone/plone.api@master`, `plone/plone.restapi@main`, and `plone/volto@main` as the default branches for developing Plone 6 Documentation. +``` - - [`documentation`](https://github.com/plone/documentation/issues) - - [`plone.api`](https://github.com/plone/plone.api/issues) - - [`plone.restapi`](https://github.com/plone/plone.restapi/issues) - - [`volto`](https://github.com/plone/volto/issues) - - Discuss during sprints, 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.com/invite/zFY3EBbjaj). +## GitHub menu -1. For first-time contributors especially, **you do not need to ask to be assigned to, or to work on, an open issue**. - As in any open source project, you can start work on open issues at your convenience. +In the upper right of the documentation, you will see the GitHub Octocat icon. - ```{tip} - Working on documentation or on issues labeled with either `33 needs: docs` or `41 lvl: easy` are the two best ways for first-timers to contribute. - This is because first-timers have a fresh perspective that might be overlooked by old-timers. - ``` +```{image} /_static/contributing/github-navigation.png +:alt: GitHub navigation menu +``` -1. Clarify the scope of work that needs to be done. - Check for previous work, assignment to another developer, or whether the requirements have changed. -1. [Assign yourself to the issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/assigning-issues-and-pull-requests-to-other-github-users). - This signals to other developers that you are working on the issue. +You can use this menu to quickly navigate to the `documentation` source repository or open an issue. +You can also browse open issues and pull requests to see what has already been reported, or work started on, to improve Plone Documentation. -From here, you can either make {ref}`contributing-quick-edits-label` or {ref}`contributing-large-edits-label`. +```{tip} +Working on documentation or on issues labeled with either `33 needs: docs` or `41 lvl: easy` are the two best ways for first-timers to contribute. +This is because first-timers have a fresh perspective that might be overlooked by old-timers. +``` (contributing-quick-edits-label)= -### Quick edits +## Edit via GitHub's website -Quick edits for minor issues, such as typographical errors, misspellings, and English grammar and syntax, can be made through the GitHub user interface. +You can make small edits for minor issues, such as typographical errors, misspellings, and English grammar and syntax, through the GitHub website. -1. Navigate to the repository as noted in {ref}`contributing-manage-on-github-label`. -1. Navigate with the `docs` directory to find the source file to edit. +1. Navigate to the repository as noted in {ref}`documentation-repositories-label`. +1. Navigate into the `docs` directory to find the source file to edit. 1. Click the {guilabel}`pencil icon` to edit the file in the browser. ```{image} /_static/edit-pencil-icon.png :alt: GitHub Edit this file ``` 1. Make edits, add a commit message, select {guilabel}`Create a new branch for this commit and start a pull request`, then click {guilabel}`Propose changes`. -1. Make your pull request against the branch `6.0`. +1. Make your pull request against the default branch of the repository. 1. Members who subscribe to the repository will receive a notification and review your request. 1. Request a review from other team members. (contributing-large-edits-label)= -### Large edits +## Edit in your local editor -For large edits, first follow the instructions in {doc}`setup-build`. +For large edits in your local editor, first follow the instructions in {doc}`setup-build`. Once you have your environment set up, then you can follow the standard practice for making a pull request. -This practice differs depending on whether you are making contributions to only the core `documentation` files, or `plone.api`, `plone.restapi` and `volto` files as well. +This practice differs according to the repository's files that you edit. + +You can then edit the documentation of either Plone in the primary repository or any of the other projects in their folder inside the {file}`/submodules` folder. (contributing-documentation-only-label)= @@ -173,7 +153,7 @@ This section describes how to make contributions to files in the `plone/document # Optionally clean the builds to avoid cache issues make clean make html - make linkcheck + make linkcheckbroken ``` ```{note} @@ -208,43 +188,30 @@ This section describes how to make contributions to files in the `plone/document ### Editing external package documentation -If you want to edit documentation of imported external packages, the process is slightly different. -We use `git submodules` to manage multiple repositories. -We imported the external repositories the `plone/documentation` repository as described in {doc}`setup-build`. - -```{important} -We currently use the branches `plone/documentation@6.0`, `plone/plone.api@master`, `plone/plone.restapi@main`, and `plone/volto@main` as the main branches for developing Plone 6 Documentation. -``` - -1. From the project root directory, sync your local `6.0` branch with its remote. - You might need to resolve conflicts. - - ```shell - git checkout 6.0 - git pull - ``` +To edit documentation of imported external packages, including `plone/plone.api`, `plone/plone.restapi`, and `plone/volto`, the process is slightly different. +Plone Documentation uses git submodules to manage multiple repositories. +You already imported the external repositories into the `plone/documentation` repository as described in {doc}`setup-build`. 1. Change your working directory to the imported package's directory under `submodules/`. ```shell # Choose one. - cd submodules/plone.api - cd submodules/plone.restapi - cd submodules/volto + cd submodules/plone.api/docs + cd submodules/plone.restapi/docs/source + cd submodules/volto/docs/source ``` -1. Update the submodule, and sync your local development branch with its remote. +1. Sync your local development branch with its remote. You might need to resolve conflicts. ```shell - git submodule update - # for plone.api git checkout master # for plone.restapi or volto git checkout main - + + # pull in the latest changes git pull ``` @@ -254,19 +221,20 @@ We currently use the branches `plone/documentation@6.0`, `plone/plone.api@master git switch -c ``` -1. Make edits to files in `docs/` using your favorite editor, and save, preview, and test. - You must run and pass the builds `html` and `linkcheck` without causing new errors. +1. Make edits to files in `submodules//` using your favorite editor, and save, preview, and test. + You must run and pass the builds `livehtml` and `linkcheckbroken` without causing new errors. ```shell # Optionally clean the builds to avoid cache issues. - # Note that for the external packages' documentation only, - # we use "docs-" as a prefix for make targets to avoid a conflicts. + # For the external packages' documentation only, you must use + # "docs-" as a prefix for `make` targets. This convention avoids + # conflicts with the `make` targets of source code. make docs-clean - make docs-html - make docs-linkcheck + make docs-livehtml + make docs-linkcheckbroken ``` -1. Back in `submodules/`, commit and push your changes to the remote. +1. Commit and push your changes to the remote. ```shell git add @@ -274,31 +242,18 @@ We currently use the branches `plone/documentation@6.0`, `plone/plone.api@master git push ``` -1. Now return to the project root directory, and update the submodule to point to the commit you just made, and push your changes to the remote repository. - - ```shell - cd ../.. - - # for plone.api - git add submodules/plone.api - git commit -m "Update submodules/plone.api tip" - - # for plone.restapi - git add submodules/plone.restapi - git commit -m "Update submodules/plone.restapi tip" - - # for Volto - git add submodules/volto - git commit -m "Update submodules/volto tip" - - git push - ``` - 1. Visit the GitHub `plone/` repository, and create a pull request against the development branch. 1. Members who subscribe to the `plone/` repository will receive a notification and review your request. 1. Request a review from other team members. +## More ways to contribute to documentation + +- Discuss during sprints, 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 Documentation chat on Discord](https://discord.com/invite/d9dZcA4Ezw). + + (contributing-documentation-code-of-conduct-label)= ## Code of Conduct @@ -308,7 +263,7 @@ See {ref}`contributing-code-of-conduct-label`. ```{toctree} --- -caption: Contributing to Documentation +caption: Contribute to Documentation maxdepth: 2 hidden: true --- diff --git a/docs/contributing/documentation/myst-reference.md b/docs/contributing/documentation/myst-reference.md index a961da0d2..fe4ab194f 100644 --- a/docs/contributing/documentation/myst-reference.md +++ b/docs/contributing/documentation/myst-reference.md @@ -112,7 +112,7 @@ For example, in the `volto` submodule, inside its `src/docs` directory, place an In your markup, use that same `docs`-root-relative path for the target, such as `/_static/user-manual/block-left-add-icon.png`. Don't use file-relative paths. -Configuration in the `conf.py` files for the main documentation and its submodules handle the resolution of `docs`-root-relative paths for you. +Configuration in the {file}`conf.py` files for the main documentation and its submodules handle the resolution of `docs`-root-relative paths for you. #### Width of media diff --git a/docs/contributing/documentation/setup-build.md b/docs/contributing/documentation/setup-build.md index 386328b8f..c1f28fd29 100644 --- a/docs/contributing/documentation/setup-build.md +++ b/docs/contributing/documentation/setup-build.md @@ -1,15 +1,15 @@ --- myst: html_meta: - "description": "How to set up the Plone Documentation locally" - "property=og:description": "How to set up the Plone Documentation locally" - "property=og:title": "Building and Checking the Quality of Documentation" + "description": "How to set up, build, and check quality of Plone Documentation locally" + "property=og:description": "How to set up, build, and check quality of Plone Documentation locally" + "property=og:title": "Set up, build, and check the quality of documentation" "keywords": "setup, build, documentation, quality, development, Vale, spell, grammar, style, check, linkcheck" --- (setup-build-label)= -# Building and checking the quality of documentation +# Set up, build, and check the quality of documentation This document covers how to set up and build the Plone Documentation and check it for quality. @@ -67,62 +67,73 @@ sudo apt-get install graphviz ### Clone `plone/documentation` -Clone the Plone Documentation repository, and change your working directory into the cloned project. -Then with a single command using `Makefile`, create a Python virtual environment, install project dependencies, pull in Volto documentation as a git submodule, build the docs, and view the results in a web browser by opening `/_build/html/index.html`. +In a terminal session, clone the Plone Documentation repository, and change your working directory into the cloned project. +Then with a single `make` command, create a Python virtual environment, install project dependencies, pull in documentation from remote repositories as a git submodule, build the documentation, and preview the results in a web browser. ```shell git clone https://github.com/plone/documentation.git cd documentation -make html +make livehtml ``` (setup-build-available-documentation-builds-label)= ## Available documentation builds -All build and check documentation commands use the file `Makefile`. - -To see the most frequently used builds, use the following command. +All build and check commands use the file `Makefile`. +To see descriptions of the builds and checks, use the following command. ```shell make help ``` -Else you can open `Makefile` to see other build formats, including PDF. +Else you can open the {file}`Makefile` file to see other build formats. +The following sections describe the most frequently used `make` commands while in the primary `documentation` folder. -### `html` +All `make` commands that build documentation will -`html` is the HTML version of the documentation. +- create a Python virtual environment, +- install requirements, +- initialize or update the `volto`, `plone.restapi`, and `plone.api` submodules, and +- finally create symlinks to the source files. + +````{tip} +If you want to build documentation for only one of the subprojects, navigate to the root of the project in the `/submodules` folder, then use any of the following commands, but with the prefix of `docs-`. ```shell -make html +cd submodules/volto +make docs-livehtml ``` - -Open `/_build/html/index.html` in a web browser. +```` ### `livehtml` -`livehtml` rebuilds Sphinx documentation on changes, with live-reload in the browser. +`livehtml` rebuilds documentation as you edit its files, with live reload in the browser. ```shell make livehtml ``` -Open http://0.0.0.0:8000/ in a web browser. +The console will give you the URL to open in a web browser. +The URL may vary, according to its configuration in the repository's {file}`Makefile`. + +```console +[sphinx-autobuild] Serving on http://127.0.0.1:8050 +``` -### `linkcheck` +### `linkcheckbroken` -`linkcheck` checks all links. +`linkcheckbroken` checks all links, returning a list of only broken links. See {ref}`authors-linkcheck-label` for configuration. ```shell -make linkcheck +make linkcheckbroken ``` -Open `/_build/linkcheck/output.txt` for a list of broken links. +Open `/_build/linkcheck/output.txt` for the entire list of links that were checked and their result. ### `vale` @@ -137,11 +148,21 @@ make vale See the output on the console for suggestions. -### `html_meta` +### `clean` + +`clean` removes all builds and cached files of the documentation. +Use this command before a build to troubleshoot issues with edits not showing up and to ensure that cached files do not hide errors in the documentation. + +```shell +make clean +``` + + +### `distclean` -`html_meta` adds a meta data section to each chapter if missing. -See {ref}`authors-html-meta-data-label` for more info. +`distclean` cleans the documentation build directory, Python virtual environment, and symlinks. +Use this command when packages that you have installed in your virtual environment yield unexpected results. ```shell -make html_meta +make distclean ``` diff --git a/docs/contributing/documentation/themes-and-extensions.md b/docs/contributing/documentation/themes-and-extensions.md index 43dd6773d..e38eb9d05 100644 --- a/docs/contributing/documentation/themes-and-extensions.md +++ b/docs/contributing/documentation/themes-and-extensions.md @@ -11,7 +11,7 @@ myst: # Themes and extensions -We learned the hard way that maintaining the design and features of documentation is a lot of work. +The Plone Documentation team learned the hard way that maintaining the design and features of documentation is a lot of work. To make all documentation maintainable, we use actively developed themes and extensions to build the documentation. @@ -21,7 +21,6 @@ When customizing the theme, we use [Sphinx Book Theme](https://sphinx-book-theme See their documentation for features, tips, and tricks that you might want to include in your documentation. We minimize the customizations of these themes as much as possible. -The one large customization is the search filter by part of the documentation, implemented in modifcations to the templates, {file}`_static/searchtools.js`, and the CSS file {file}`_static/custom.css`. ## Extensions diff --git a/docs/glossary.md b/docs/glossary.md index 41299fb25..91a5cb75a 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -850,4 +850,11 @@ portlets Portlets are widgets that can be inserted in predefined locations in pages in {term}`Classic UI`. Portlets are most commonly used to add sidebars to the left or right of the main page content. +Diátaxis framework + Plone Documentation uses the [Diátaxis framework](https://www.diataxis.fr/), a systematic approach to technical documentation authoring. + +Vale + [Vale](https://vale.sh/) is an open-source, command-line tool that helps maintain a consistent and on-brand voice in documentation. + Plone Documentation uses it to check spelling, English grammar and syntax, and style guides. + ```