"rsync for cloud storage" - Google Drive, S3, Dropbox, Backblaze B2, One Drive, Swift, Hubic, Wasabi, Google Cloud Storage, Azure Blob, Azure Files, Yandex Files
Go azure-blobazure-blob-storageazure-filesbackblaze-b2cloud-storagedropboxencryptionftpfuse-filesystemgogolanggoogle-cloud-storagegoogle-driveonedriveopenstack-swiftrclones3sftpsyncwebdav
docs: update contributing guide regarding markdown documentation
albertony122890799fb9
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex b711e4377..781f7e8ed 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -306,8 +306,10 @@ with modules beneath.- ...commands- cmdtest - end-to-end tests of commands, flags, environment variables,...- docs - the documentation and website- - content - adjust these docs only - everything else is autogenerated- - command - these are auto-generated - edit the corresponding .go file+ - content - adjust these docs only, except those marked autogenerated+ or portions marked autogenerated where the corresponding .go file must be+ edited instead, and everything else is autogenerated+ - commands - these are auto-generated, edit the corresponding .go file- fs - main rclone definitions - minimal amount of code- accounting - bandwidth limiting and statistics- asyncreader - an io.Reader which reads ahead@@ -345,6 +347,36 @@ with modules beneath.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.++HTML pages, served as website <rclone.org>, are generated from the Markdown,+using [Hugo](https://gohugo.io). Note that when generating the HTML pages,+there is currently used a different algorithm for generating header anchors+than what GitHub uses for its Markdown rendering. For example, in the HTML docs+generated by Hugo any leading `-` characters are ignored, which means when+linking to a header with text `--config string` we therefore need to use the+link `#config-string` in our Markdown source, which will not work in GitHub's+preview where `#--config-string` would be the correct link.++Most of the documentation are written directly in text files with extension+`.md`, mainly within folder `docs/content`. Note that several of such files+are autogenerated (e.g. the command documentation, and `docs/content/flags.md`),+or contain autogenerated portions (e.g. the backend documentation under+`docs/content/commands`). These are marked with an `autogenerated` comment.+The sources of the autogenerated text are usually Markdown formatted text+embedded as string values in the Go source code, so you need to locate these+and edit the `.go` file instead. The `MANUAL.*`, `rclone.1` and other text+files in the root of the repository are also autogenerated. The autogeneration+of files, and the website, will be done during the release process. See the+`make doc` and `make website` targets in the Makefile if you are interested in+how. You don't need to run these when adding a feature.+If you add a new general flag (not for a backend), then document it in`docs/content/docs.md` - the flags there are supposed to be inalphabetical order.@@ -373,19 +405,20 @@ the source file in the `Help:` field.create a new list item. Also, for enumeration texts like name ofcountries, it looks better without an ending period/full stop character.-The only documentation you need to edit are the `docs/content/*.md`-files. The `MANUAL.*`, `rclone.1`, website, etc. are all auto-generated-from those during the release process. See the `make doc` and `make-website` targets in the Makefile if you are interested in how. You-don't need to run these when adding a feature.+When writing documentation for an entirely new backend,+see [backend documentation](#backend-documentation).-Documentation for rclone sub commands is with their code, e.g.-`cmd/ls/ls.go`. Write flag help strings as a single sentence on a single-line, without a period/full stop character at the end, as it will be-combined unmodified with other information (such as any default value).+If you are updating documentation for a command, you must do that in the+command source code, e.g. `cmd/ls/ls.go`. Write flag help strings as a single+sentence on a single line, without a period/full stop character at the end,+as it will be combined unmodified with other information (such as any default+value).-Note that you can use [GitHub's online editor](https://help.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository)-for small changes in the docs which makes it very easy.+Note that you can use+[GitHub's online editor](https://help.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository)+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.## Making a release