ansible/docs/docsite/rst/dev_guide/style_guide/index.rst

279 lines
8.6 KiB
ReStructuredText
Raw Normal View History

.. _style_guide:
*******************
Ansible style guide
*******************
Welcome to the Ansible style guide!
To create clear, concise, consistent, useful materials on docs.ansible.com, follow these guidelines:
.. contents::
:local:
Linguistic guidelines
=====================
We want the Ansible documentation to be:
* clear
* direct
* conversational
* easy to translate
We want reading the docs to feel like having an experienced, friendly colleague
explain how Ansible works.
Stylistic cheat-sheet
---------------------
This cheat-sheet illustrates a few rules that help achieve the "Ansible tone":
+-------------------------------+------------------------------+----------------------------------------+
| Rule | Good example | Bad example |
+===============================+==============================+========================================+
| Use active voice | You can run a task by | A task can be run by |
+-------------------------------+------------------------------+----------------------------------------+
| Use the present tense | This command creates a | This command will create a |
+-------------------------------+------------------------------+----------------------------------------+
| Address the reader | As you expand your inventory | When the number of managed nodes grows |
+-------------------------------+------------------------------+----------------------------------------+
| Use standard English | Return to this page | Hop back to this page |
+-------------------------------+------------------------------+----------------------------------------+
| Use American English | The color of the output | The colour of the output |
+-------------------------------+------------------------------+----------------------------------------+
Header case
-----------
Headers should be written in sentence case. For example, this section's title is
``Header case``, not ``Header Case`` or ``HEADER CASE``.
Avoid using Latin phrases
-------------------------
Latin words and phrases like ``e.g.`` or ``etc.``
are easily understood by English speakers.
They may be harder to understand for others and are also tricky for automated translation.
2020-01-13 22:46:44 +01:00
Use the following English terms in place of Latin terms or abbreviations:
+-------------------------------+------------------------------+
2020-01-13 22:46:44 +01:00
| Latin | English |
+===============================+==============================+
2020-01-13 22:46:44 +01:00
| i.e | in other words |
+-------------------------------+------------------------------+
| e.g. | for example |
+-------------------------------+------------------------------+
| etc | and so on |
+-------------------------------+------------------------------+
| via | by/ through |
+-------------------------------+------------------------------+
| vs./versus | rather than/against |
+-------------------------------+------------------------------+
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 <https://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:
.. code-block:: rst
###############
Developer guide
###############
* ``***`` with overline, for chapters:
.. code-block:: rst
*******************
Ansible style guide
*******************
* ``===`` for sections:
.. code-block:: rst
Mechanical guidelines
=====================
* ``---`` for subsections:
.. code-block:: rst
Internal navigation
-------------------
* ``^^^`` for sub-subsections:
.. code-block:: rst
Adding anchors
^^^^^^^^^^^^^^
* ``"""`` for paragraphs:
.. code-block:: rst
Paragraph that needs a title
""""""""""""""""""""""""""""
Syntax highlighting - Pygments
------------------------------
The Ansible documentation supports a range of `Pygments lexers <https://pygments.org/>`_
for `syntax highlighting <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#code-examples>`_ to make our code examples look good. Each code-block must be correctly indented and surrounded by blank lines.
The Ansible documentation allows the following values:
* none (no highlighting)
* ansible-output (a custom lexer for Ansible output)
* bash
* console
* csharp
* ini
* json
* powershell
* python
* rst
* sh
* shell
* shell-session
* text
* yaml
* yaml+jinja
For example, you can highlight Python code using following syntax:
.. code-block:: rst
.. code-block:: python
def my_beautiful_python_code():
pass
Internal navigation
-------------------
`Anchors (also called labels) and links <https://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_rst:
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:
.. code-block:: rst
:ref:`unique_page`
:ref:`this page <unique_page>`
The second example adds custom text for the link.
Adding links to modules and plugins
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Ansible 2.10 and later require the extended Fully Qualified Collection Name (FQCN) as part of the links:
.. code-block:: text
ansible_collections. + FQCN + _module
For example:
.. code-block:: rst
:ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.builtin.first_found_lookup>`
displays as :ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.builtin.first_found_lookup>`.
Modules require different suffixes from other plugins:
* Module links use this extended FQCN module name with ``_module`` for the anchor.
* Plugin links use this extended FQCN plugin name with the plugin type (``_connection`` for example).
.. code-block:: rst
:ref:`arista.eos.eos_config <ansible_collections.arista.eos.eos_config_module>`
:ref:`kubernetes.core.kubectl connection plugin <ansible_collections.kubernetes.core.kubectl_connection>`
.. note::
``ansible.builtin`` is the FQCN for modules included in ``ansible.base``. Documentation links are the only place you prepend ``ansible_collections`` to the FQCN. This is used by the documentation build scripts to correctly fetch documentation from collections on Ansible Galaxy.
2020-01-13 22:46:44 +01:00
.. _local_toc:
Adding local TOCs
^^^^^^^^^^^^^^^^^
The page you're reading includes a `local TOC <https://docutils.sourceforge.io/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:
.. code-block:: rst
.. contents::
:local:
More resources
==============
These pages offer more help with grammatical, stylistic, and technical rules for documentation.
.. toctree::
:maxdepth: 1
basic_rules
voice_style
trademarks
grammar_punctuation
spelling_word_choice
2020-01-13 22:46:44 +01:00
search_hints
resources
.. seealso::
:ref:`community_documentation_contributions`
How to contribute to the Ansible documentation
:ref:`testing_documentation_locally`
How to build the Ansible documentation
`irc.freenode.net <http://irc.freenode.net>`_
#ansible-docs IRC chat channel