On Sat, Oct 8, 2016 at 9:18 AM, Stephen Finucane <step...@that.guru> wrote:
> We have one for coding and could do with one for docs. > > Signed-off-by: Stephen Finucane <step...@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 <step...@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 _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
