1
0
mirror of https://github.com/ARM-software/workload-automation.git synced 2025-03-21 01:59:13 +00:00

doc/contributing: Add a guide to documentation styles

Add a documentation style guide to aid in keeping a consistent style
when adding new documentation.
This commit is contained in:
Marc Bonnici 2018-06-29 10:39:06 +01:00 committed by setrofim
parent c67994260d
commit 60989ef66c

View File

@ -1,5 +1,8 @@
Contributing Code
=================
Contributing
============
Code
----
We welcome code contributions via GitHub pull requests. To help with
maintainability of the code line we ask that the code uses a coding style
@ -53,3 +56,130 @@ submitting a pull request:
Once you have your contribution is ready, please follow instructions in `GitHub
documentation <https://help.github.com/articles/creating-a-pull-request/>`_ to
create a pull request.
--------------------------------------------------------------------------------
Documentation
-------------
Headings
~~~~~~~~
To allow for consistent headings to be used through out the document the
following character sequences should be used when creating headings
::
=========
Heading 1
=========
Only used for top level headings which should also have an entry in the
navigational side bar.
*********
Heading 2
*********
Main page heading used for page title, should not have a top level entry in the
side bar.
Heading 3
==========
Regular section heading.
Heading 4
---------
Sub-heading.
Heading 5
~~~~~~~~~
Heading 6
^^^^^^^^^
Heading 7
"""""""""
--------------------------------------------------------------------------------
Configuration Listings
~~~~~~~~~~~~~~~~~~~~~~
To keep a consistent style for presenting configuration options, the preferred
style is to use a `Field List`.
(See: http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists)
Example::
:parameter: My Description
Will render as:
:parameter: My Description
--------------------------------------------------------------------------------
API Style
~~~~~~~~~
When documenting an API the currently preferred style is to provide a short
description of the class, followed by the attributes of the class in a
`Definition List` followed by the methods using the `method` directive.
(See: http://docutils.sourceforge.net/docs/user/rst/quickref.html#definition-lists)
Example::
API
===
:class:`MyClass`
----------------
:class:`MyClass` is an example class to demonstrate API documentation.
``attribute1``
The first attribute of the example class.
``attribute2``
Another attribute example.
methods
"""""""
.. method:: MyClass.retrieve_output(name)
Retrieve the output for ``name``.
:param name: The output that should be returned.
:return: An :class:`Output` object for ``name``.
:raises NotFoundError: If no output can be found.
Will render as:
:class:`MyClass` is an example class to demonstrate API documentation.
``attribute1``
The first attribute of the example class.
``attribute2``
Another attribute example.
methods
^^^^^^^
.. method:: MyClass.retrieve_output(name)
Retrieve the output for ``name``.
:param name: The output that should be returned.
:return: An :class:`Output` object for ``name``.
:raises NotFoundError: If no output can be found.