openstack/openstack-manuals
Code Issues Proposed changes
a62242d6e0
openstack-manuals/doc/contributor-guide/source/rst-conv/gen-guidelines.rst
OlgaGusarenko c10da1ec38 [Contributor Guide] RST section finished 
1. Adds the following subsections:
   * Introduction to RST
   * Tables
   * Images
   * Profiling
   * Lists
   * Inline markups
   * Decorations
   * Commenting
2. Restructures the toc
3. Creates separate files for each subsection included in the
RST-related folder for simpler maintenance.

Change-Id: I08568fb37755109552edf9692b8f259660550a69
2015-10-20 11:14:32 +03:00

1.5 KiB
Raw Blame History

General guidelines

Lines length

Wrap source lines so that lines length does not exceed 79 characters. This requirement matches PEP8 standards (from Python) and helps with side-by-side diffs on reviews.

Note

Exception to this rule is the content of code-block elements and links within the references.

When formatting a table that presupposes long lines of text, give preference to one of the following methods over the table directive:

  • Format a table using the list-table directive.
  • Format a table using the csv-table directive.
  • Format information as definition lists to avoid tables where possible.

Space and tab characters

  • Do not use tab characters within the code, use space characters instead.
  • Do not place space characters at the end of lines. If used, the checkniceness test will fail because of trailing whitespaces.

Indentation

Use indentation very carefully and keep it consistent since it is significant for content nesting. Any indentation that differs from the previous one in length, terminates the current level of content either introducing a new content sublevel, or shifting to an upper content level.

Use indentation to format the nested content within:

  • Definition lists
  • Admonitions (notes, warnings, and so on)
  • Code blocks
  • List and CSV tables

For more information on how to format elements from the list above, see the related section of this chapter.