go/rclone
1
0
Fork 0
mirror of https://github.com/rclone/rclone.git synced 2025-08-10 06:09:44 +02:00
Code Issues Releases Activity

docs: update contributing guide regarding markdown documentation

Browse Source
This commit is contained in:
albertony
2025-07-13 23:13:07 +02:00
parent 65078d5846
commit 122890799f
1 changed files with 46 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
CONTRIBUTING.md
View File

@@ -306,8 +306,10 @@ with modules beneath.
- ...commands - ...commands
- cmdtest - end-to-end tests of commands, flags, environment variables,... - cmdtest - end-to-end tests of commands, flags, environment variables,...
- docs - the documentation and website - docs - the documentation and website
- content - adjust these docs only - everything else is autogenerated - content - adjust these docs only, except those marked autogenerated
- command - these are auto-generated - edit the corresponding .go file 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 - fs - main rclone definitions - minimal amount of code
- accounting - bandwidth limiting and statistics - accounting - bandwidth limiting and statistics
- asyncreader - an io.Reader which reads ahead - 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. 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 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 in `docs/content/docs.md` - the flags there are supposed to be in
alphabetical order. alphabetical order.
@@ -373,19 +405,20 @@ the source file in the `Help:` field.
create a new list item. Also, for enumeration texts like name of create a new list item. Also, for enumeration texts like name of
countries, it looks better without an ending period/full stop character. countries, it looks better without an ending period/full stop character.
The only documentation you need to edit are the `docs/content/*.md` When writing documentation for an entirely new backend,
files. The `MANUAL.*`, `rclone.1`, website, etc. are all auto-generated see [backend documentation](#backend-documentation).
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.
Documentation for rclone sub commands is with their code, e.g. If you are updating documentation for a command, you must do that in the
`cmd/ls/ls.go`. Write flag help strings as a single sentence on a single command source code, e.g. `cmd/ls/ls.go`. Write flag help strings as a single
line, without a period/full stop character at the end, as it will be sentence on a single line, without a period/full stop character at the end,
combined unmodified with other information (such as any default value). 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) Note that you can use
for small changes in the docs which makes it very easy. [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 ## Making a release