.. _writing_docs: Writing and building documentation ================================== The documentation is written using `reStructuredText language `_ and is built with `sphinx-build `_ through a tox environment. Style guide ----------- Follow these guidelines when writing the documentation. Tense and voice ^^^^^^^^^^^^^^^ For reference and general task-based docs use the "imperative mood". These docs should be straightforward and conventional. For example: .. code-block:: rst To create a user, run: .. code-block:: sql CREATE USER my_user; For tutorials, the docs can be more casual and conversational but must also be straightforward and clear. For example: .. code-block:: rst In this lab, start with a fresh cluster. Make sure to stop and clean up the cluster from the previous labs. Future and conditional tenses ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Avoid future tense (will) and conditional tenses (would, could, should). These tenses lack precision and can create passive voice. Use future tense when an action occurs in the future, for example: .. code-block:: rst This feature will be removed in a future release. While present tense is strongly preferred, future tense can be useful and accurate in an "if/then" phrase. For example, it's okay to write: .. code-block:: rst If you perform this action, another action will occur. The conditional tense is okay only if you explain the conditions and any action to take. For example, use: .. code-block:: rst A message should appear. If it doesn't, restart the server. Person ^^^^^^ Use second person (you) when referring to the user. Don't use "the user" which is third person. Use first person plural (we) to refer to the authors of the docs. For example, use: .. code-block:: rst We recommend that you restart your server. Instead of: .. code-block:: rst Developers recommend that you restart your server. However, don't use first person plural when talking about how the software works or in an example. For example, use: .. code-block:: rst Next, Barman processes the instruction. Instead of: .. code-block:: rst Next, we process the instruction. Line length ^^^^^^^^^^^ When possible do not overflow 88 characters per line in the source files. In general, exceptions for this rule are links. Sentence length ^^^^^^^^^^^^^^^ Avoid writing sentences with more than 26 words. Long sentences tend to make the content complicated. Contractions ^^^^^^^^^^^^ In keeping with the casual and friendly tone, use contractions. However, use common contractions (isn't, can't, don't). Don't use contractions that are unclear or difficult to pronounce (there'll). Numbers ^^^^^^^ Spell out numbers zero through nine. Use digits for numbers 10 and greater. Spell out any number that starts a sentence. For this reason, avoid starting a sentence with a long or complex number. Dates ^^^^^ When specifying dates for human readability, use the DD mmm YYYY format with a short month name in English. Where the date is being used in a column in a table, use a leading 0 on the day of month for easier alignment, for example, 01 Jan 2024. When specifying dates as solely numbers, use `ISO8601 `_ format; YYYY/MM/DD. This is the internationally accepted, disambiguous format. Use it where you may expect the date to be read by automated systems. Capitalization ^^^^^^^^^^^^^^ Capitalization rules: * Use sentence-case for headings (including column headings in tables). * Capitalize the first letter in each list item except for function and command names that are naturally lower case. * Capitalize link labels to match the case of the topic you're linking to. * Capitalize proper nouns and match the case of UI features. * Don't capitalize the words that make up an initialization unless they're part of proper noun. For example, single sign-on is not a proper noun even though it's usually written as the initialism SSO. Punctuation ^^^^^^^^^^^ Punctuation rules: * Avoid semicolons. Instead, use two sentences. * Don't join related sentences using a comma. This syntax is incorrect. * Don't end headings with a period or colon. * Use periods at the end of list items that are a sentence or that complete a sentence. If one item in a list uses a period, use a period for all the items in that list. * Use the `Oxford (AKA serial) comma `_. "This" without a noun ^^^^^^^^^^^^^^^^^^^^^ Avoid using "this" without a noun following. Doing so can lead to ambiguity. For example, use: .. code-block:: rst This error happens when… Instead of: .. code-block:: rst This happens when... Directing users up and down through a topic ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Don't use words like "above" and "below" to refer to previous and following sections. Link to the section instead or use "earlier" or "later". It also isn't necessary to use the words "the following" to refer to list items. These words are empty. So, for example, use: .. code-block:: rst The color palette includes: Instead of: .. code-block:: rst The palette includes the following colors: Bold (**text**) ^^^^^^^^^^^^^^^ Use for UI elements. For example: .. code-block:: rst The output of ``barman show-backup`` includes: * **Backup Size**: the size of the backup. * **Estimated Cluster Size**: the estimated size of the cluster once the backup is restored. Also for roles and users. For example: .. code-block:: rst Run as **root**: .. code-block:: bash dnf install barman Courier (AKA inline code or monospace ``text``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use for parameters, commands, text in configuration files, file paths, packages and utility names. For example: .. code-block:: rst If you need to type the ``ls`` or ``dd`` command, add a setting to a ``configuration=file`` or just refer to ``/etc/passwd``, then this is the font treatment to use. Code blocks ^^^^^^^^^^^ Use to provide code or configuration samples. Example for code sample: .. code-block:: rst Execute this query: .. code-block:: sql SELECT * FROM pg_stat_activity; Example for configuration sample: .. code-block:: rst Create the file ``/etc/barman.conf`` with: .. code-block:: ini [barman] ; System user barman_user = barman ; Directory of configuration files. Place your sections in separate files with ; .conf extension ; For example place the 'main' server section in /etc/barman.d/main.conf configuration_files_directory = /etc/barman.d Italics (*text*) ^^^^^^^^^^^^^^^^ Use for book titles. For example: .. code-block:: rst We recommend you read *PostgreSQL 16 Administration Cookbook*. Links ^^^^^ Avoid using the URL as the label. For example, use: .. code-block:: rst For more information about backups in Postgres, see `Backup and Restore `_. Instead of: .. code-block:: rst For more information about backups in Postgres, see `https://www.postgresql.org/docs/current/backup.html`_. Admonitions (notes, warnings, hints, etc.) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When applicable use `admonitions `_. For multiple, consecutive admonitions, use separate admonitions. Tables ^^^^^^ Use `tables `_ to display structured information in an easy-to-read format. Lists ^^^^^ Use `lists `_ to display information in items: * Numbered (ordered): Use to list information that must appear in order, like tutorial steps. * Bulleted (unordered): Use to list related information in an easy-to-read way. Use period at the end of each list item. Images ^^^^^^ Use `images `_ to clarify a topic, but use them only as needed. Images are put inside the folder ``docs/images``. Cross-reference labels standard ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When creating cross-reference labels in Sphinx, please follow these guidelines to ensure consistency and clarity: 1. Use Hyphens: Separate words in labels with a hyphen. For example: ``.. _backup-overview:`` 2. Hierarchical Prepending: For each ``.rst`` file, prepend labels with the higher-level section label, followed by any intermediate sub-section labels. This way, the full hierarchy is represented in the label. For example, a file called ``backup.rst`` can have the following label: ``.. _backup:`` Then, any subsequent labels in this file should start with ``backup-``. For a sub-section labeled ``Overview`` the label would be ``_backup-overview:``. For another sub-section in ``Overview`` the label would be like: ``.. _backup-overview-other-section-under-overview:`` Handling Included Files """"""""""""""""""""""" If your ``.rst`` file uses the ``.. include::`` directive, evaluate whether the included files are closely related to the parent document: * Related Example: In a file ``commands.rst`` with the label: ``.. _commands:`` if you include another file, like ``commands/backup.rst``, which is related, you would label the latter as: ``.. _commands-backup:`` * Independent Example: If the included section is not directly related, you may treat it as an independent section, without the hierarchical label prepending. Purpose of This Standard """""""""""""""""""""""" Following this labeling standard helps us: * Easily trace the source of cross-references. * Avoid label duplication. * Simplify navigation for developers and end-users. By adhering to these guidelines, we can create clear and maintainable documentation that enhances usability and understanding. Building the documentation -------------------------- You can build the documentation in three different formats: * HTML: Contains the full documentation. * PDF: Same as HTML, excluding the section :ref:`contributor_guide`. * Linux man page: contains only the sections :ref:`configuration` and :ref:`commands`. The documentation is built through a tox environment named docs. HTML documentation ^^^^^^^^^^^^^^^^^^ To build the HTML documentation, run: .. code-block:: bash tox -e docs -- html To view the HTML documentation, open the file ``docs/_build/html/index.html`` using your web browser. PDF documentation ^^^^^^^^^^^^^^^^^ To build the PDF documentation, run: .. code-block:: bash tox -e docs -- latexpdf To view the PDF documentation, open the file ``docs/_build/latex/Barman.pdf`` using your PDF reader. Linux man page ^^^^^^^^^^^^^^ To build the Linux man page, run: .. code-block:: bash tox -e docs -- man To view the Linux man page, run: .. code-block:: bash man docs/_build/man/barman.1