[ovs-dev] [PATCH 1/2] docs: Add documentation style guide
russell at ovn.org
Tue Oct 18 18:44:10 UTC 2016
On Sat, Oct 8, 2016 at 9:18 AM, Stephen Finucane <stephen at that.guru> wrote:
> We have one for coding and could do with one for docs.
> Signed-off-by: Stephen Finucane <stephen at that.guru>
> DocumentationStyle.rst | 274 ++++++++++++++++++++++++++++++
> 1 file changed, 274 insertions(+)
> create mode 100644 DocumentationStyle.rst
> diff --git a/DocumentationStyle.rst b/DocumentationStyle.rst
> new file mode 100644
> index 0000000..d37f3c0
> --- /dev/null
> +++ b/DocumentationStyle.rst
> @@ -0,0 +1,274 @@
> + Copyright (c) 2016 Stephen Finucane <stephen at that.guru>
> + Licensed under the Apache License, Version 2.0 (the "License"); you
> + not use this file except in compliance with the License. You may
> + a copy of the License at
> + http://www.apache.org/licenses/LICENSE-2.0
> + Unless required by applicable law or agreed to in writing, software
> + distributed under the License is distributed on an "AS IS" BASIS,
> + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> See the
> + License for the specific language governing permissions and
> + under the License.
> + Convention for heading levels in Open vSwitch documentation:
> + ======= Heading 0 (reserved for the title in a document)
> + ------- Heading 1
> + ~~~~~~~ Heading 2
> + +++++++ Heading 3
> + ''''''' Heading 4
> + Avoid deeper levels because they do not render well.
> +Open vSwitch Documentation Style
> +This file describes the documentation style used in all documentation
> found in
> +Open vSwitch. All documents should follow this guide.
> +reStructuredText vs. Sphinx
> +reStructuredText (reST) is the syntax, while Sphinx is a documentation
> +generator. Sphinx introduces a number of extensions to reST, like the
> +``:ref:`` role, which can and should be used in documentation, but these
> +not work correctly on GitHub. As such, these extensions should not be
> used in
> +any documentation in the root level, such as the ``README``.
> +Many of the basic documentation guidelines match those of the `coding
> +guide <CodingStyle.md>`__.
> +- Use reStructuredText (reST) for all documentation.
> + Sphinx extensions can be used, but only for documentation in the
> + ``Documentation`` folder.
> + .. note::
> + Some legacy documents may exist in other formats. When time allows,
> + should be converted to reST.
> +- Limit lines at 79 characters.
> + .. note::
> + An exception to this rule is text within code-block elements that
> cannot be
> + wrapped and links within references.
> +- Use spaces for indenation.
> +- Match indentation levels.
> + A change in indentation level usually signifies a change in content
> + by either closing the existing level or introducing a new level.
> +- Avoid trailing spaces on lines.
> +- Use the following headers levels.
> + | ======= Heading 0 (reserved for the title in a document)
> + | ------- Heading 1
> + | ~~~~~~~ Heading 2
> + | +++++++ Heading 3
> + | ''''''' Heading 4
I dropped this section on headings as it was repeated shortly after in a
section called "Titles".
I applied this series to master. Thanks!
More information about the dev