7.4. Documentation

7.4.1. Style Guides

7.4.1.1. SIMP documentation (simp-doc)

SIMP documentation uses ReStructuredText roles to keep formatting consistent, automatically cross-reference glossary terms, and generate external hyperlinks to web resources.

When available, prefer using a relevant role from the tables below over inline formatting such as bold *text* or double-backticks (``):

Roles already built into Sphinx

Purpose

Example

Code

Notes

Code snippets

ensure => true

:code:`ensure => true`

CLI commands

yum update -y

:command:`yum update -y`

Files

/etc/simp/version.x.y

:file:`/etc/simp/version.{x}.{y}`

Use curly braces {foo} to denote variable path elements

Programs

mcstransd

:program:`mcstransd`

Glossary terms

SIMP

:term:`SIMP`

Automatically creates internal hyperlink to term in Glossary
Custom roles, created for simp-doc

Purpose

Example

Code

Notes

Packages (e.g., RPM, RubyGem)

simp-utils

:package:`simp-utils`

Puppet Modules

simp/simplib

:pupmod:`simp/simplib`

When text is in org-name or org/name format, will auto-link to Puppet Forge URL

GitHub repos

simp/simp-doc

:github:`simp/simp-doc`

Auto-links to GitHub repo URL

Jira issues

SIMP-8464

:jira:`SIMP-8464`

Auto-links to (SIMP project) Jira issue URL
Inline formatting

Purpose

Example

Code

Notes

Literal text

keyword

``keyword``

ReST’s basic markup for fixed-width text. Only use this if there isn’t an appropriate role.

Internal hyperlinks

Changelogs

:ref:`changelogs`

:ref: crosslinks are actually built-in roles, but we’ll group them here

External hyperlinks

SIMP website

`SIMP website <https://www.simp-project.com>`_

External hyperlinks are decorated with a special icon

7.4.1.2. SIMP Puppet modules

Documentation for Puppet modules should follow the Puppet Strings Style Guide.

7.4.1.3. SIMP git repositories

SIMP project git repositories should contain a README.md file at their top level.