Documentation Style Guide

The Open SoC Debug documentation is written in reStructuredText (rST). It is then processed by Sphinx to generate various output formats, including HTML (for online documentation) and PDF (for offline reading and printing).

A good syntax overview is included in the Sphinx documentation reStructuredText Primer.

For the OSD docs, we have a couple of additional conventions.

Headlines and Sections

rST does not have strict rules regarding the formatting of section headers. To keep things consistent, we follow the rules recommended by the Python Style Guide. That is:

  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • ", for paragraphs

Tables

Tables are a tricky business, especially if both the PDF and the HTML output should look reasonable and editing should be easy. We included the Sphinx extension “flat-table” extension, which is also used by the Linux Kernel documentation, as an easier way of writing tables as nested list. This makes tables a bit harder to read in source code, but easier to edit and clearer in diffs. In addition, we use the tabularcolumns directive to explicitly specify the width of the table columns in LaTeX/PDF output.

The following code snippet shows how to use flat-table together with a LaTeX column width specification required for good-looking PDF output:

.. tabularcolumns:: |p{\dimexpr 0.20\linewidth-2\tabcolsep}|p{\dimexpr 0.20\linewidth-2\tabcolsep}|p{\dimexpr 0.60\linewidth-2\tabcolsep}|
.. flat-table:: Example Table Title
  :widths: 2 2 6
  :header-rows: 1

  * - address
    - name
    - description

  * - 0x0000
    - ``MOD_ID``
    - module type identifier

Notes:

  • Specify the width as fractions of 1 (equal to 100 %) in the tabularcolumn directive.
  • Specify the width of columns as fraction of 10 in the ::widths: parameter.
  • Do not change anything in the tabularcolumns directive except for the width unless you have double-checked that both HTML and PDF output look fine.
  • Give tables a caption.

Figures

Pixel Graphics

You can use PNG and JPEG images as usual. Make sure to provide them in sufficiently large resolution (> 150 dpi) to be suitable for printing.

Vector Graphics

For vector graphics, use SVG.

If you include the figure in your document, use .* instead of .svg as file extension. This instructs Sphinx to use the most appropriate extension for the output format. For HTML, SVG images are included directly. For PDF/LaTeX, the images are first converted to PDF using Inkscape.

Example:

.. figure:: img/overview.*
   :alt: Open SoC Debug architecture overview
   :name: fig:spec:architecture:overview

   High-level overview of the Open SoC Debug architecture.

:numref:`Figure %s <fig:spec:architecture:overview>` shows the different components in a typical Open SoC Debug-based debug system.

Notes:

  • Make sure not to use any non-standard font inside the graphic, as the SVG will be displayed as-is to users who might not have the font installed (SVG does not embed fonts; the only thing you can do is create a path out of the text, removing the ability to edit the text.)
  • SVG images do not show up in PDFs generated by ReadTheDocs at the moment.