.. _index: **************************************** Pylons Project Documentation Style Guide **************************************** .. meta:: :description: This chapter is the style guide used for documentation of all Pylons Project projects. :keywords: Style Guide, Documentation .. _dsg-introduction: Introduction ============ This document is aimed at authors of and contributors to documentation for projects under the Pylons Project. This document describes style and reStructuredText syntax used in project documentation. We provide examples, including reStructuredText code and its rendered output, for both visual and technical reference. The source code of this guide is located in its `project repository on GitHub `_. For Python coding style guidelines, see `Coding Style `_. We have adopted the convention from :RFC:`2119` for key words. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in :RFC:`2119`. Other conventions throughout this guide are adopted and adapted from `Documenting Python `_, `Plone Documentation Style Guide `_, and `Write The Docs `_. .. _dsg-contributing: Contributing to a project's documentation ----------------------------------------- All projects under the Pylons Projects follow the guidelines established at `How to Contribute `_. When submitting a pull request for the first time in a project, sign its ``CONTRIBUTORS.txt`` and commit it along with your pull request. Contributors to documentation should be familiar with `reStructuredText `_ (reST) for writing documentation. Most projects use `Sphinx `_ to build documentation from reST source files, and `Read The Docs `_ (RTD) for publishing them on the web. Experience with Sphinx and RTD may be helpful, but not required. .. _dsg_testing-documentation: Testing Documentation --------------------- Before submitting a pull request, documentation should be tested locally. Ultimately testing of documentation must be done before merging a pull request. This is typically done through a project's integration with Travis CI or Appveyor. * Use Sphinx's ``make html`` command to build the HTML output of the documentation without errors or warnings. Some projects use ``tox -e docs`` or just ``tox`` to invoke Sphinx's ``make html``. Most other build utilities like `restview `_ and `readme_renderer `_ test only a single file and do not support cross-references between files. * If documentation has doctests and uses :ref:`dsg-sphinx-extension-doctest`, then run Sphinx's ``make doctest`` command. * Optionally use Sphinx's ``make linkcheck`` command to verify that links are valid and to avoid bit rot. It is acceptable to ignore broken links in a project's change log and history. Narrative and API documentation should occasionally have its links checked. * Optionally use Sphinx's ``make epub`` and ``make latexpdf`` or ``make xelatex`` commands to build epub or PDF output of the documentation. This project's `repository `_ has an example of how to configure Sphinx, tox, and Travis to build documentation. .. _dsg-documentation-structure: Documentation structure ======================= This section describes the structure of documentation and its files. .. _dsg-location: Location -------- Documentation source files should be contained in a folder named ``docs`` located at the root of the project. Images and other static assets should be located in ``docs/_static``. reST directives must refer to files either relative to the source file or absolute from the top source directory. For example, in ``docs/narr/source.rst``, you could refer to a file in a different directory as either: .. code-block:: rst .. include:: ../diff-dir/diff-source.rst or: .. code-block:: rst .. include:: /diff-dir/diff-source.rst. .. _dsg-file-naming: File naming ----------- reST source files and static assets should have names that consist only of lowercase letters (``a-z``), numbers (``0-9``), periods (``.``), and hyphens (``-``) instead of underscores (``_``). Files must start a letter. reST source files should have the extension of ``.rst``. Image files may be any format, but must have standard file extensions that consist of three letters (``.gif``, ``.jpg``, ``.png``, ``.svg``). ``.gif`` and ``.svg`` are not currently supported by PDF builders in Sphinx. However you can use an asterisk (``*``) as a :index:`wildcard extension` instead of the actual file extension. This allows the Sphinx builder to automatically select the correct image format for the desired output. For example: .. code-block:: rst .. image:: ../_static/pyramid_request_processing.* will select the image ``pyramid_request_processing.svg`` for the HTML documentation builder, and ``pyramid_request_processing.png`` for the PDF builder. See the related `Stack Overflow post `_. .. _dsg-index: Index ----- Documentation must have an index file whose purpose is to serve as a home page for the documentation, including references to all other pages in the documentation. The index file should be named ``index.rst``. Each section, or a subdirectory of reST files such as a tutorial, must contain an ``index.rst`` file. The index should contain at least a :ref:`dsg-table-of-contents` through the :ref:`toctree ` directive. The index should include a reference to both a search page and a general index page, which are automatically generated by Sphinx. See below for an example. .. code-block:: rst * :ref:`genindex` * :ref:`search` * :ref:`genindex` * :ref:`search` .. _dsg-glossary: Glossary -------- Documentation may have a glossary file. If present, it must be named ``glossary.rst``. This file defines terms used throughout the documentation. Its content must begin with the directive ``glossary``. An optional ``sorted`` argument should be used to sort the terms alphabetically when rendered, making it easier for the user to find a given term. Without the argument ``sorted``, terms will appear in the order of the ``glossary`` source file. Example: .. code-block:: rst .. glossary:: :sorted: voom Theoretically, the sound a parrot makes when four-thousand volts of electricity pass through it. pining What the Norwegien Blue does when it misses its homeland, for example, pining for the fjords. The above code renders as follows. .. rst-class:: glossary simple pining What the Norwegian Blue does when it misses its homeland, for example, pining for the fjords. voom Theoretically, the sound a parrot makes when four-thousand volts of electricity pass through it. References to glossary terms appear as follows. .. code-block:: rst :term:`voom` :term:`voom` Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term. .. _dsg-change-history: Change history -------------- Either a reference to a change history log file in the project or its inclusion in the documentation should be present. Change history should include feature additions, deprecations, bug fixes, release dates and versions, and other significant changes to the project. .. _dsg-file-encoding: File encoding ------------- All documentation source files must be in UTF-8 encoding to allow special characters, including em-dash (``—``) and tree diagram characters. .. _dsg-general-guidance: General guidance ================ This section describes the general voice, tone, and style that documentation should follow. It also includes things for authors to consider when writing to your audience. Accessibility ------------- Consider that your audience includes people who fall into the following groups: - People who do not use English as their first language (English language rules are insanely complex). According to our web statistics for docs.pylonsproject.org, about 36% of all readers of documentation under the Pylons Project do not use English as their first language. And only about 32% of all visitors are from the United States, United Kingdom, Canada, Australia, New Zealand, and Ireland. - Visually impaired readers (a comma makes a huge difference to a screen reader, adding a "breath", much like a musical breath symbol). - Readers who don't have college-level reading comprehension. - Folks with reading disabilities. Voice ----- It is acceptable to address the reader as "you". This helps make documentation, especially tutorials, more approachable. "You" is also less formal than "the user". Avoid sentence run-ons ---------------------- Instead of using long sentences, consider breaking them into multiple shorter sentences. Long complicated sentences are more difficult to understand than shorter, clearer sentences. Consider that your audience is not familiar with your content. That is why they are reading your documentation. Gender ------ Except for speaking for oneself, the author should avoid using pronouns that identify a specific gender. Neutral gender pronouns "they", "them", "their", "theirs", "it", and "its" are preferred. Never use the hideous and clumsy "he/she". Style ----- Avoid hype and marketing. Avoid words that can frustrate or discourage the reader if they are not able to complete or understand a concept. Such words include "simple", "just", "very", "easy", and their derivations. For example, "Simply run the command ``foo bar``, and you're up and running!" will frustrate a user who has neither installed the requirements for ``foo`` nor configured it to execute ``bar``. English Syntax -------------- Use proper spelling, grammar, and punctuation. `English Language & Usage `_ is a good resource. Never use "and/or". If you cannot figure out whether you should use "and" or "or", and are tempted to use the lazy "and/or", then write the sentence so it is clear. Avoid abbreviations. Spell out words. Avoid "etc.", "e.g.", and "i.e.". They do not translate well or read well by screen readers for the visually impaired. It is lazy, and sounds pretentious. Writers seldom get the usage or punctuation right. Instead spell it out to their meanings of "and so on", "for example", and "in other words". .. _dsg-page-structure: Documentation page structure ============================ Each page should contain in order the following. #. The main heading. This will be visible in the table of contents. .. code-block:: rst ================ The main heading ================ #. Meta tag information. The "meta" directive is used to specify HTML metadata stored in HTML META tags. Metadata is used to describe and classify web pages in the World Wide Web in a form that is easy for search engines to extract and collate. .. code-block:: rst .. meta:: :description: This chapter describes how to edit, update, and build the Pyramid documentation. :keywords: Pyramid, Style Guide The above code renders as follows. .. code-block:: xml #. Introduction paragraph. .. code-block:: rst Introduction ------------ This chapter is an introduction. #. Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on. .. _dsg-documentation-content: Documentation page content ========================== This section describes the content of documentation source files. .. _dsg-use-of-whitespace: Use of whitespace ----------------- Narrative documentation is not code, and should therefore not adhere to :pep:`8` standards or other line length conventions. There is no maximum line length. Lines should be the length of one sentence, without hard wraps. Lines should not end with white space. When a paragraph contains more than one sentence, its sentences should be written one per line. This makes it easier to edit and find differences when updating documentation. For example: .. code-block:: rst This is the first sentence in a paragraph. This is the second sentence in a paragraph. This is a new paragraph. Which renders as follows. This is the first sentence in a paragraph. This is the second sentence in a paragraph. This is a new paragraph. All indentation should be 4 spaces. Do not use tabs to indent. Each section should have two trailing blank lines to separate it from the previous section. A section heading should have a blank line following its underline and before its content. A line feed or carriage return should be used at the end of a file. All other whitespace is defined by reST syntax. .. _dsg-table-of-contents: Table of contents ----------------- ``toctree`` entries should exclude the file extension. For example: .. code-block:: rst .. toctree:: :maxdepth: 2 narr/introduction narr/install narr/firstapp .. _dsg-headings: Headings -------- Chapter titles, sections, sub-sections, sub-sub-sections, and sub-sub-sub-sections within a chapter (usually a single reST file) are indicated with markup and are displayed as headings at various levels. Conventions are adopted from `Documenting Python, Sections `_. Headings are rendered in HTML as follows: ==================== ============================ ======== Heading Level underline/overline character HTML ==================== ============================ ======== Title ``*`` ``

`` Sections ``=`` ``

`` Sub-sections ``-`` ``

`` Sub-sub-sections ``^`` ``

`` Sub-sub-sub-sections ``"`` ``

`` ==================== ============================ ======== The chapter title of this document, *Documentation Style Guide*, has the following reST code. .. code-block:: rst ************************* Documentation Style Guide ************************* Chapter titles should be over- and underlined with asterisks (``*``). The heading for this section, *Documentation content*, has the following reST code: .. code-block:: rst Documentation content ===================== The heading for this sub-section, *Headings*, has the following reST code: .. code-block:: rst Headings -------- Sub-sub-section, and sub-sub-sub-section headings are shown as follows. Heading Level 4 ^^^^^^^^^^^^^^^ This is a sub-sub-section. .. code-block:: rst Heading Level 4 ^^^^^^^^^^^^^^^ Heading Level 5 """"""""""""""" This is a sub-sub-sub-section. .. code-block:: rst Heading Level 5 """"""""""""""" .. _dsg-paragraphs: Paragraphs ---------- A paragraph of text looks exactly like this paragraph. Paragraphs must be separated by two line feeds. .. _dsg-links: Links to websites ----------------- It is recommended to use inline links to keep together the context or link label with the URL. Avoid the use of targets and links at the end of the page, because the separation makes it difficult to update and translate. Here is an example of inline links, our preferred method. .. code-block:: rst `TryPyramid `_ The above code renders as follows. `TryPyramid `_ .. seealso:: See also :ref:`dsg-cross-reference-links` for generating links throughout the entire documentation. .. _dsg-cross-reference-links: Cross-reference links --------------------- To create cross-references to a document, arbitrary location, object, or other items, use variations of the following syntax. * ``:role:`target``` creates a link to the item named ``target`` of the type indicated by ``role``, with the link's text as the title of the target. ``target`` may need to be disambiguated between documentation sets linked through intersphinx, in which case the syntax would be ``deform:overview``. * ``:role:`~target``` displays the link as only the last component of the target. * ``:role:`title ``` creates a custom title, instead of the default title of the target. .. _dsg-cross-referencing-documents: Cross-referencing documents ^^^^^^^^^^^^^^^^^^^^^^^^^^^ To link to pages within this documentation: .. code-block:: rst :doc:`glossary` The above code renders as follows. :doc:`glossary` .. _dsg-cross-referencing-arbitrary-locations: Cross-referencing arbitrary locations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To support cross-referencing to arbitrary locations in any document and between documentation sets via intersphinx, the standard reST labels are used. For this to work, label names must be unique throughout the entire documentation including externally linked intersphinx references. There are two ways in which you can refer to labels, if they are placed directly before a section title, a figure, or table with a caption, or at any other location. This section has a label with the syntax ``.. _label_name:`` followed by the section title. .. code-block:: rst .. _dsg-cross-referencing-arbitrary-locations: Cross-referencing arbitrary locations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To generate a link to that section with its title, use the following syntax. .. code-block:: rst :ref:`dsg-cross-referencing-arbitrary-locations` The above code renders as follows. :ref:`dsg-cross-referencing-arbitrary-locations` The same syntax works for figures and tables with captions. For labels that are not placed as mentioned, the link must be given an explicit title, such as ``:ref:`title