diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2196b3f0..a03b407f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -348,11 +348,13 @@ If you are adding a new feature then please update the documentation. The documentation sources are generally in Markdown format, in conformance with the CommonMark specification and compatible with GitHub Flavored -Markdown (GFM). The markdown format is checked as part of the lint operation -that runs automatically on pull requests, to enforce standards and consistency. -This is based on the [markdownlint](https://github.com/DavidAnson/markdownlint) -tool, which can also be integrated into editors so you can perform the same -checks while writing. +Markdown (GFM). The markdown format and style is checked as part of the lint +operation that runs automatically on pull requests, to enforce standards and +consistency. This is based on the [markdownlint](https://github.com/DavidAnson/markdownlint) +tool by David Anson, which can also be integrated into editors so you can +perform the same checks while writing. It generally follows Ciro Santilli's +[Markdown Style Guide](https://cirosantilli.com/markdown-style-guide), which +is good source if you want to know more. HTML pages, served as website , are generated from the Markdown, using [Hugo](https://gohugo.io). Note that when generating the HTML pages, @@ -381,7 +383,7 @@ If you add a new general flag (not for a backend), then document it in alphabetical order. If you add a new backend option/flag, then it should be documented in -the source file in the `Help:` field. +the source file in the `Help:` field: - Start with the most important information about the option, as a single sentence on a single line. @@ -403,6 +405,30 @@ the source file in the `Help:` field. as an unordered list, therefore a single line break is enough to create a new list item. Also, for enumeration texts like name of countries, it looks better without an ending period/full stop character. +- You can run `make backenddocs` to verify the resulting Markdown. + - This will update the autogenerated sections of the backend docs Markdown + files under `docs/content`. + - It requires you to have [Python](https://www.python.org) installed. + - The `backenddocs` make target runs the Python script `bin/make_backend_docs.py`, + and you can also run this directly, optionally with the name of a backend + as argument to only update the docs for a specific backend. + - **Do not** commit the updated Markdown files. This operation is run as part of + the release process. Since any manual changes in the autogenerated sections + of the Markdown files will then be lost, we have a pull request check that + reports error for any changes within the autogenerated sections. Should you + have done manual changes outside of the autogenerated sections they must be + committed, of course. +- You can run `make serve` to verify the resulting website. + - This will build the website and serve it locally, so you can open it in + your web browser and verify that the end result looks OK. Check specifically + any added links, also in light of the note above regarding different algorithms + for generated header anchors. + - It requires you to have the [Hugo](https://gohugo.io) tool available. + - The `serve` make target depends on the `website` target, which runs the + `hugo` command from the `docs` directory to build the website, and then + it serves the website locally with an embedded web server using a command + `hugo server --logLevel info -w --disableFastRender --ignoreCache`, so you + can run similar Hugo commands directly as well. When writing documentation for an entirely new backend, see [backend documentation](#backend-documentation). @@ -419,6 +445,11 @@ for small changes in the docs which makes it very easy. Just remember the caveat when linking to header anchors, noted above, which means that GitHub's Markdown preview may not be an entirely reliable verification of the results. +After your changes have been merged, you can verify them on +[tip.rclone.org](https://tip.rclone.org). This site is updated daily with the +current state of the master branch at 07:00 UTC. The changes will be on the main +[rclone.org](https://rclone.org) site once they have been included in a release. + ## Making a release There are separate instructions for making a release in the RELEASE.md