Headers should be written in sentence case. For example, this section's title is
``Header case``, not ``Header Case`` or ``HEADER CASE``.
reStructuredText guidelines
===========================
The Ansible documentation is written in reStructuredText and processed by Sphinx.
We follow these technical or mechanical guidelines on all rST pages:
Header notation
---------------
`Section headers in reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_
can use a variety of notations.
Sphinx will 'learn on the fly' when creating a hierarchy of headers.
To make our documents easy to read and to edit, we follow a standard set of header notations.
We use:
* ``###`` with overline, for parts::
###############
Developer guide
###############
* ``***`` with overline, for chapters::
*******************
Ansible style guide
*******************
*******************
Welcome to the Ansible Style Guide
* ``===`` for sections::
==================================
Mechanical guidelines
=====================
* ``---`` for subsections::
Follow these guidelines to create clear, concise, useful community contributions and documentation. This guide helps us make the content on ansible.com consistent.
Internal navigation
-------------------
* ``^^^`` for sub-subsections::
Adding anchors
^^^^^^^^^^^^^^
* ``"""`` for paragraphs::
Paragraph that needs a title
""""""""""""""""""""""""""""
Internal navigation
-------------------
`Anchors (also called labels) and links <http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_
work together to help users find related content.
Local tables of contents also help users navigate quickly to the information they need.
All internal links should use the ``:ref:`` syntax.
Every page should have at least one anchor to support internal ``:ref:`` links.
Long pages, or pages with multiple levels of headers, can also include a local TOC.
Adding anchors
^^^^^^^^^^^^^^
* Include at least one anchor on every page
* Place the main anchor above the main header
* If the file has a unique title, use that for the main page anchor::
.._unique_page::
* You may also add anchors elsewhere on the page
Adding internal links
^^^^^^^^^^^^^^^^^^^^^
* All internal links must use ``:ref:`` syntax. These links both point to the anchor defined above::
:ref:`unique_page`
:ref:`this page <unique_page>`
The second example adds custom text for the link.
Adding local TOCs
^^^^^^^^^^^^^^^^^
The page you're reading includes a `local TOC <http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents>`_.
If you include a local TOC:
* place it below, not above, the main heading and (optionally) introductory text
* use the ``:local:`` directive so the page's main header is not included
* do not include a title
The syntax is::
..contents::
:local:
More resources
==============
These pages offer more help with grammatical, stylistic, and technical rules for documentation.
..toctree::
..toctree::
:maxdepth:1
:maxdepth:1
@ -24,10 +157,11 @@ Follow these guidelines to create clear, concise, useful community contributions