7.4. Documentation

7.4.1. Style Guides 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://simp-project.com>`_ External hyperlinks are decorated with a special icon SIMP Puppet modules

Documentation for Puppet modules should follow the Puppet Strings Style Guide. SIMP git repositories

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