More Markdown format lint #8771
Merged
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a continuation of #8678, to make sure our Markdown docs uses a valid and consistent format. Here I've started to work through the command docs and backend docs, and have quite many issues, mostly things like this:
Since the files in focus this time are partially or entirely generated from source code, the process was to: build rclone, generate markdown, lint, fix issues in the sources of the markdown text, and repeat. This was done as a local and manual process for now, but the future plan is to get the linting of these running on GitHub pull requests alongside our other markdown linters, e.g. as I did a PoC on with #8704.
The work in this area is not done, but with these changes there are risk of git conflicts, so I wanted to ship a batch as soon as possible, and see if we are able to merge it before I continue with a new iteration. Also, I wanted to see the result of the checks for edits in autogenerated sections, that runs on the PR. I have run some tests locally, to look for any regressions in the command line help and the generated HTML pages, which are based on the same sources.
Next iteration (which I now plan as a new PR after this is merged) will start by going through the backend options - I've only updated the static parts of the backend docs so far in this PR.
Note that with the command docs, there is an issue with the cobra library we use, it generates parts of the markdown and currently the linter reports a couple of issues in that. I have changed it locally for now, to be able to lint the generated command docs without issues, but will have to think about what to do with this later.
What is the purpose of this change?
Was the change discussed in an issue or in the forum before?
Checklist