From cd73c2f51ae3b17a7b4f2430a712ff2a7ade5847 Mon Sep 17 00:00:00 2001 From: Jeff Ohrstrom Date: Fri, 27 Dec 2024 12:31:37 -0500 Subject: [PATCH] add styleguide with a few things (#1048) --- STYLEGUIDE.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 STYLEGUIDE.md diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md new file mode 100644 index 00000000..b8088c4c --- /dev/null +++ b/STYLEGUIDE.md @@ -0,0 +1,52 @@ +# Open OnDemand Documentation Styleguide + +## Headings + +### Titles + +Heading titles should capitalize every major word and lowercase +every minor word. + + * major words: Nouns, verbs (including linking verbs), adjectives, adverbs, pronouns, and all words of four letters or more are considered major words. + + * minor words: Short (i.e., three letters or fewer) conjunctions, short prepositions, and all articles are considered minor words. + +### RST Title Underlines Characters + +Sphinx rst files allow for any non-alphanumeric character to be the +title underlines. It will even allow for different pages to have different +conventions/underline characters for different sections. + +Throughout this codebase title underlines are varied. However, at some point +we should standardize to this convention which `source/customizations.rst` +follows: + +* H1: === +* H2: --- +* H3: ... +* H4: ``` +* H5: TBD + +## Code-block spacing + +The convention in RST for code-block spacing is to have the content +have 3 spaces as shown below. + +```raw + .. code-block:: sh + + sudo systemctl try-restart apache2 +``` + +This project breaks that convention by using 2 spaces in the `code-block` +content as shown below. + +```raw + .. code-block:: sh + + sudo systemctl try-restart apache2 +``` + +While this may look more visually applealing as the content is left aligned +with the `code-block` text above it - text editors and IDEs show an extra space +at this point and it's a bit off putting.