diff options
author | Marc Bonnici <marc.bonnici@arm.com> | 2018-06-29 10:39:06 +0100 |
---|---|---|
committer | setrofim <setrofim@gmail.com> | 2018-06-29 11:04:09 +0100 |
commit | 60989ef66cc1f154ba326ecb3f98abac9bde466e (patch) | |
tree | b7e7a33ab43563ff71a80bd7b7b10a6088777a7b /doc/source | |
parent | c67994260dd3fd4804896b401aa3c7aee62244c5 (diff) |
doc/contributing: Add a guide to documentation styles
Add a documentation style guide to aid in keeping a consistent style
when adding new documentation.
Diffstat (limited to 'doc/source')
-rw-r--r-- | doc/source/developer_information/developer_reference/contributing.rst | 134 |
1 files changed, 132 insertions, 2 deletions
diff --git a/doc/source/developer_information/developer_reference/contributing.rst b/doc/source/developer_information/developer_reference/contributing.rst index dd25bd6c..c4e2f3f3 100644 --- a/doc/source/developer_information/developer_reference/contributing.rst +++ b/doc/source/developer_information/developer_reference/contributing.rst @@ -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. |