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 (``):
| 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 |
| 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 |
| 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 |
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.