docs: add guidelines for contributing to Cilium's documentation #16738
Conversation
Sphinx attempts to apply syntax highlighting on literal blocks (the
blocks marked with "code-block" directives with no language provided,
"parsed-literal" directives, or literal block markers ("::"). The
documentation [1] explains that it defaults on Python:
> The default language to highlight source code in. The default is
> 'default'. It is similar to 'python3'; it is mostly a superset of
> 'python' but it fallbacks to 'none' without warning if failed.
> 'python3' and other languages will emit warning if failed.
We barely use any Python in the repository. When no language is
provided, this is most of the time because the snippet is just some
unstructured code that should be displayed verbatim, or, in the case of
parsed literals, commands to type in a terminal. Let's overwrite the
default and prevent the default highlighting based on Python3's syntax.
[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-highlight_language
Signed-off-by: Quentin Monnet <quentin@isovalent.com>
qmonnet
added
area/documentation
We had a short discussion on Slack, and the conclusion was that it was better to fix structural issues when they arise, since they are quite rare. Until we happen to have the same kind of breakage all the time, no need to have guidelines for that :) |
Not a bad idea, but I don't think there's a consensus on that - I think that for code blocks for example we have a mix of 2, 3, 4, 8 spaces in different files (or sometimes in a single one). And if we make it too strict, nobody will follow it. Do you have suggestions in particular? One thing that comes to mind is that we prefer to wrap long lines, I forgot to mention that. |
No, I was mostly just confused when contributing about what rules I should follow. So far I've just rolled with using the same style as the one around what I was modifying. |
qmonnet
force-pushed
the
pr/doc-style-guidelines
branch
from
46bbda5
to
25819b6
Compare
Add a set of recommendations on style and formatting for contributing to Cilium's documentation. The current guidelines are mostly about RST formatting for now, but can be extended with whatever directions may help produce a better documentation in the future. Signed-off-by: Quentin Monnet <quentin@isovalent.com>
qmonnet
force-pushed
the
pr/doc-style-guidelines
branch
from
25819b6
to
5b2c6ab
Compare
|
I added a (hopefully consensual) note on line wrapping: Body
----
Wrap the lines for long sentences or paragraphs. There is no fixed convention
on the length of lines, but targeting a width of about 80 characters should be
safe in most circumstances.Based on the reviews and the Documentation action passing, I'll mark as ready-to-merge. I'm happy to add a note on indent and spacing as a follow-up if we settle on something. |
qmonnet
added
the
ready-to-merge
This PRs a set of recommendations on style and formatting for contributing to Cilium's documentation. The current guidelines are mostly about RST formatting for now, but can be extended with whatever directions may help produce a better documentation in the future.
Some of these guidelines are simply suggestions: they may not have been the topic of any particular discussion before, and feedback is welcome. I spent some time looking at the RST specification, but I don't claim to have the right point-of-view on every item.
One follow-up item to add would be a recommendation on the structure, in particular regarding nesting (or not nesting) RST fragments. See this discussion with suggestions from @nbusseneau for reference, but I'm not sure a consensus was reached at the time.
[First commit also relates to the documentation, but focuses on syntax highlighting and cancels Sphinx's default attempt to highlight snippets based on Python3's syntax.]