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 + +- Include a license (see this file) in all docs. + +- Most importantly, always build and display documentation before submitting + changes! Docs aren't unit testable, so visible inspection is necessary. + +File Names +---------- + +- Use hyphens as space delimiters. For example: ``my-readme-document.rst`` + +- Use lowercase filenames. + + .. note:: + An exception to this rule is any documents found in the root-level of the + project. + +Titles +------ + +- Use the following headers levels. + + | ======= Heading 0 (reserved for the title in a document) + | ------- Heading 1 + | ~~~~~~~ Heading 2 + | +++++++ Heading 3 + | ''''''' Heading 4 + + .. note:: + + Avoid using lower heading levels by rewriting and reorganizing the + information. + +- Under- and overlines should be of the same length as that of the heading + text. + +- Use "title case" for headers. + +Code +---- + +- Use ``::``, the ``code`` role or the ``code-block:: <syntax>`` role to prefix + code. + +- Prefix commands with ``$``. + +- Where possible, include fully-working snippets of code. If there + pre-requisites, explain what they are and how to achieve them. + +Admonitions +----------- + +- Use admonitions to call attention to important information.:: + + .. note:: + + This is a sample callout for some useful tip or trick. + + Example admonitions include: ``warning``, ``important``, ``note``, ``tip`` or + ``seealso``. + +Tables +------ + +- Use either graphic tables, list tables or CSV tables. + +Graphic tables +~~~~~~~~~~~~~~ + +:: + + .. table:: OVS-Linux kernel compatibility + + ============ ============== + Open vSwitch Linux kernel + ============ ============== + 1.4.x 2.6.18 to 3.2 + 1.5.x 2.6.18 to 3.2 + 1.6.x 2.6.18 to 3.2 + ============ ============== + +:: + + .. table:: OVS-Linux kernel compatibility + + +--------------+---------------+ + | Open vSwitch | Linux kernel | + +==============+===============+ + | 1.4.x | 2.6.18 to 3.2 | + +--------------+---------------+ + | 1.5.x | 2.6.18 to 3.2 | + +--------------+---------------+ + | 1.6.x | 2.6.18 to 3.2 | + +--------------+---------------+ + +.. note:: + The ``table`` role (`` .. table:: <name>``) can be safely omitted. + +List tables +~~~~~~~~~~~ + +:: + + .. list-table:: OVS-Linux kernel compatibility + :widths: 10 15 + :header-rows: 1 + + * - Open vSwitch + - Linux kernel + * - 1.4.x + - 2.6.18 to 3.2 + * - 1.5.x + - 2.6.18 to 3.2 + * - 1.6.x + - 2.6.18 to 3.2 + +CSV tables +~~~~~~~~~~ + +:: + + .. csv-table:: OVS-Linux kernel compatibility + :header: Open vSwitch, Linux kernel + :widths: 10 15 + + 1.4.x, 2.6.18 to 3.2 + 1.5.x, 2.6.18 to 3.2 + 1.6.x, 2.6.18 to 3.2 + +Cross-referencing +----------------- + +- To link to an external file or document, include as a link.:: + + Here's a `link <http://openvswitch.org>`__ to the Open vSwitch website. + + + Here's a `link`_ in reference style. + + .. _link: http://openvswitch.org + +- You can also use citations.:: + + Refer to the Open vSwitch documentation [1]_. + + References + ---------- + + .. [1]: http://openvswitch.org + +- To cross-reference another doc, use the ``doc`` role.:: + + Here is a link to the :doc:`/README.rst` + + .. note:: + This is a Sphinx extension. Do not use this in any top-level documents. + +- To cross-reference an arbitrary location in a doc, use the ``ref`` role.:: + + .. _sample-crossref + + Title + ~~~~~ + + Hello, world. + + Another Title + ~~~~~~~~~~~~~ + + Here is a cross-reference to :ref:`sample-crossref`. + + .. note:: + This is a Sphinx extension. Do not use this in any top-level documents. + +Figures and Other Media +----------------------- + +- All images should be in ASCII format and included in code-blocks to preserve + formatting. + +- Include other reStructuredText verbatim in a current document + +Comments +-------- + +- Comments are indicated by means of the ``..`` marker.:: + + .. TODO(stephenfin) This section needs some work. This TODO will not + appear in the final generated document, however. + +Useful Links +------------ + +* `Quick reStructuredText + <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__ +* `Sphinx Documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`__ -- 2.7.4 _______________________________________________ dev mailing list dev@openvswitch.org http://openvswitch.org/mailman/listinfo/dev
