[ovs-dev] [PATCH 1/2] docs: Add documentation style guide

Russell Bryant 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
> may
> +      not use this file except in compliance with the License. You may
> obtain
> +      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,
> WITHOUT
> +      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> See the
> +      License for the specific language governing permissions and
> limitations
> +      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
> will
> +not work correctly on GitHub. As such, these extensions should not be
> used in
> +any documentation in the root level, such as the ``README``.
> +
> +Basics
> +------
> +
> +Many of the basic documentation guidelines match those of the `coding
> style
> +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,
> these
> +    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
> nesting,
> +  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!

-- 
Russell Bryant



More information about the dev mailing list