Document Authors Guide

The following outlines the set of suggested format to be used when making additions to the document. The use of consistent macros and labels helps improve the overall readability of the document and assists in longer term maintenance.

Chapters and Sections

The format is to a single line of text, underlined by non-ASCII characters. Numbering is disabled. Use concise text.

The length of the underline must be at least as long as the line of text
The order of the non-ASCII characters denotes chapters / sections / subsections / etc.

In the pmixexamples docs, the sequence of underline characters we use are:
Chapter
=======
Section
-------
Subsection
^^^^^^^^^^
Subsubsection
+++++++++++++
Meaning: underlines made of = denotes chapters, underlines made of - denotes sections, underlines made of ^ denotes subsections, and underlines made of + denote subsubsections.

References to Chapters and Sections

Cross-reference Chapters and Sections in the local document by name, as they are unnumbered.

General format:
.. _label:
:ref:`label`
For example:
.. _pmixexamples:other:misc:author-guide:

Document Authors Guide
======================
The Author guide is in :ref:`pmixexamples:other:misc:author-guide`.
Rendered example:

The Author guide is in Document Authors Guide.

Call-out Boxes

All call-outs follow the same general syntax.

General format:

.. callout:: Text to include in colored box.

For example:

.. important:: This is important example text.

The following are the preferred call-outs to use in the document.

important - Important details of interest to the reader that might be worth additional attention, especially for pointing out possible pitfalls.

Important

This is important example text.
note - Miscellaneous note to add in the document.

Note

This is note example text.
todo - Marker for a item to do in the document. (See: Support for todo items)

Todo

This is todo example text.
warning - Warning for something in the document.

Warning

This is warning example text.
seealso - References to other documentation or external documents.

See also

Microservice intro pmixexamples:introduction
Introductory information

My External Documentation, Using Foobar
Documentation for foobar, part of the external project Foozilla.

Naming Scheme

A hierarchical naming scheme is used for labels to help reflect the location of content.

General format:
.. _pmixexamples:<A>:<X>:<Y>:<Z>:
For example, this Authors Guide lives under the /misc directory and has a top-level label that provides a logical namesapce for the document.
.. _pmixexamples:other:misc:author-guide:
All labels (sub-sections, figures, tables, etc.) in this file will have the same namespace and will have this same prefix. For example, the dummy example figure has the label
fig:pmixexamples:other:misc:author-guide:dummy
Note

We recommend using a short prefix for Figures sand Tables to aid recognition of the kind of label, e.g., fig: for figures, tab: for tables.

Figures

Format figures with a fixed pixel width between 400px and 800px, as rendering them relatively to the window size may show them with abnormal sizes and resolutions. Make sure that images have reasonable enough resolutions, e.g., 100 dpi or larger. Figures should be centered.

General format:

:ref:`label`                # Link text is (full) caption
:ref:`Short string <label>` # Link text is "Short string"

 .. figure:: path/to/figure.png
    :name:  label
    :align: center
    :width: 400px

    Full caption

Note

Numbered cross-references would use :numref:`label`, but are generally avoided in the docs.

References to Figures

Cross-reference to Figures in the local document by number.

Example:
In :ref:`Dummy <fig:pmixexamples:other:misc:author-guide:dummy>` we have a dummy figure.

In :ref:`fig:pmixexamples:other:misc:author-guide:dummy` we have a dummy figure.

.. figure:: images/dummyfig.png
   :name:  fig:pmixexamples:other:misc:author-guide:dummy
   :align: center
   :width: 400px

   A caption for my figure that is sort of long.
Rendered example:

In Dummy we have a dummy figure.

In A caption for my figure that is sort of long. we have a dummy figure.

Fig. 1 A caption for my figure that is sort of long.

Easy conversion of PDF images to PNG with ImageMagic

Use the density option to define the DPI the PDF should be rendered for the conversion.

shell$ convert -density 125 image.pdf image.png

Reference to Bibliography

Insert a citation to an item contained in the bibliography.

General format:
:cite:`<TERM>`
For example:
The IEEE glossary of term is useful :cite:`pmix:standard:5.0`.
Rendered example:

The IEEE glossary of term is useful [B1].

Reference to Glossary Terms

Cross-reference to glossary terms.

General format:
:term:`<TERM>`
For example:
This is a reference to term :term:`HPC` inline with text.
Rendered example:

This is a reference to term HPC inline with text.

Hyperlinks to other (RST) files

Create a hyperlink to document in local files using :doc:.

General format:
:doc:`link text <PAGE_PATH>`
For example:
You should read the :doc:`Author Guide </other/misc/authors>`.
Rendered example:

You should read the Author Guide.

Note

The page path is relative to top dir in the git tree.

Hyperlinks to URL

Create a hyperlink a URL.

General format:
`link text <link>`_
For example:
`Process Management Interface for Exascale (PMIx) <https://pmix.org/>`_
Rendered example:

Process Management Interface for Exascale (PMIx)

Note

The the trailing underscore (_) is important.

An example for Glossary Terms

The Terminology and Acronyms are helpful for centralizing terminology.

You would reference the term Sphinx like that and here is a link to a term while showing text in the topic including the term in angle brackets reStructuredText.