Doc Style Guide and Conventions (Rough Draft)

doc_style_guide_draft.md

    General:
    - Key words (must/not, should/not, may/can) follow IETF conventions

    Structure:
    - In general, follow the [OpenStack Heading Guidelines](https://docs.openstack.org/doc-contrib-guide/writing-style/general-writing-guidelines.html) with regard to sections and headings; in particular, section and subsection titles delineating overall categories of tasks/topics and be in gerund (i.e. with "ing", e.g. "Editing code", "Debugging files"), while those concerning a concept or reference topic should be a noun (e.g. "General considerations", "Requirements") and lowest level topic/task titles should generally be in imperative ("Create a code cell", "Get help", etc) where reasonable
    - 1 L1 Heading for title with component/topic name in Title Case, use ###### with overline, on first line, keep to a few words
    - All other headings: Two blank lines should preceede them; use sentence case, with a capital letter beginning a parenthetic Like this: Begin with caps 
    - L2 Headings for main heads, will appear in sidebar so keep them short: Use ========= with overline
    - L3 headings for subheads, use ~~~~~~
    - L4 Headings: Use sparingly, only if really needed, use ---------
    - Related components at the bottom: L3 heading, bullets, 2 blank lines before, try for 2-4 links if included
    - All files with Related components should contain at least one L2 section; if only one, can be  entitled Overview
    - Typically, for files with multiple sections or longer than one page, a summary section of a few lines length is helpful before the first section, summarizing the functionality discussed in the section and its purpose
    - Name of component/topic should be in first sentence, Title Case, bold on first use
    
    Technical:
    - Markdown, Github-flavored (``.md``) for any non-documentation rendered text files in the root of the repo, e.g. ``README``, ``CONTRIBUTING``, etc.
    - reStructuredText, (reST, ``.rst``) for documentation format, i.e. any user-visible files in the ``/doc`` directory
    - Where not otherwise contradicted by this guide or specific individual requirements, a subset of Markdown corresponding to that cross-compatible with reST should be preferred where possible; e.g. ``*italic*`` vs. ``_italic_``, ``*`` for bulleted lists, double backtick for inline code vs. single, etc.
    - Documentation should build with no warnings with ``Sphinx`` in nitpicky mode
    - Lower case filenames, rst extension, hyphens as space deliminators, short but descriptive
    - End files with a newline (blank line)
    - 1 blank line after all headings and before and after paragraphs, directives and "|"s
    - Use Line Feed (LF, ``\n``) as the End of Line character on all platforms
    - Use UTF-8 for all files (with no BOM, as dictated by the UTF-8 standard); do not use Windows Notepad as this adds a BOM and can otherwise corrupt files easily
    - Indicate special characters (e.g. em dash, en dash, etc) by simply including them inline with Unicode
    - Suggested to avoid non-ASCII characters where minimal downside/need exists, and recommended to keep used characters within the standard Latin-1 set where an additional range is not required by the specific usage, or an existing proper name or other identifier uses them
    - Spaces, no tabs for indentation and otherwise
    - Natural indents (3 spaces) for directives, 4 spaces for further indents beyond that in code
    - No hard wrap, put each sentence on its own line, and try to keep them under 180 characters
    - Place section links above the section with one blank line between them and the section, and two blank lines between sections (as appropriate for that section level) between the link and the preceding text.
    - Always use single backticks around link titles
    - Eliminate any trailing whitespace before commiting
    - Try to keep individual files to under around ~500 lines; split into separate topics beyond that
    
    reST Style Elements:
    - Filenames/paths: Use :file: and ``/`` for deliminators e.g. :file:`path/to/test.py`. Example filenames should be all lowercase with no spaces or special characters unless called for by the application; real filenames should follow their actual case. Use {descriptive-name} for placeholders.
    - Keyboard Shortcuts: Use :kbd: to format, Ctrl/Alt/Shift as abbreviations (instead of Command/Option), - with no spaces to separate, and title case (including capital letters for letter keys; always include Shift explicitly if needed) e.g. :kbd:`Ctrl-Alt-Shift-P`. Use the key name or symbol as printed on a standard keyboard. For any configurable shortcut, you should include "by default" to indicate this, and must include at least one another means the command can be accessed if available (e.g. via a menu or toolbar), which should be done for all shortcuts and should include all means of executing the command, if multiple others exist.
    - GUI elements (names of things in the UI): Use :guilabel: , e.g. :guilabel:`Name`; make sure to use the exact name and capitalization as printed in the UI, except for the proper names of Spyder modules and plugins, which should always be written in Title Case ("History Log", "Project Explorer", "Find in Files", etc.)
    - Menu items and preference panes: Use :menuselection: to format and ``-->`` to separate, e.g. `` :menuselection:`Project --> New Project` ``, make sure to use the exact name and capitalization of each level element
    - Short commands/lines of code (under 20-30 characters), use `` , e.g. ``code`` 
    - For any code longer than one line, ~20-30 characters, or that is otherwise important to emphasize rather than just mention, use ``code-block::`` tags, closed with ``end``, and specify the programming language (bash for command line, python for python, ini for configuration files, etc.). PEP 8 should be followed for Python code, with all "recommended"/"preferred"/"suggested" guidelines being treated as *should* i.e. only broken with appropriate justification in a situation requiring them; similarly, PEP 257 for docstrings where needed. Additionally, all code must be valid Python 3 unless specifically meant to illustrate a distinction with Python 2, and code should for the time being fall under the common subset supported by Spyder's supported platforms (currently, Python 2.7 and Python 3.4-3.6).
    - All links must be inline (not bare), should be https if available, and should, generally, be written as a reference with `` `Test Link Name`_ `` and then included in full at after the end of the paragraph in which it appears, e.g. `` .. _Test Link Name: https://www.example.com/ `` . A block of links should be separated from paragraphs above and below by one blank line, with no blank lines between links. Make sure to check that your links, as the build will automatically check for broken ones. Strip anything unnecessary (parameters, referrers, etc) off the end. As the base docs are in US English, any links should be to the English, desktop version of the site.
    * Use enumerated lists with ``#. `` to list items with a clearly defined order, otherwise, use bulleted lists with ``* ``. Include a space between the bullet/number and the text. No blank line between elements, unless a sublist is present, but blank lines around the list. Sublist should have no spaces around elements. You should try to avoid more than two levels of lists if at all possible, and keep lists to between 3 and 10-20 elements; anything shorter should be written in prose, and anything longer should be simplified or broken into multiple lists/sublists.
    - Use ``note::`` for general callouts, ``warning::`` to warn users against procedures with potential serious consequences, and ``important::`` for key points that users don't want to miss. However, use these sparingly, only when clearly called for. Always make them separate blocks, with a blank line between the start of the block, like:
    ```
    .. Note::
       
       This is a note.
    ```
    
    Images/Figures:
    - Organize images into directories following the Google drive
    - Lower case file names and extensions, separate with underscores, 3-character extensions
    - For ease of visibility, explanatory images should be full width; expository or those with very simple subjects can be half-width, right aligned
    - Use PNG for all images, except photographs over 100 KB as a PNG (use moderately compressed JPEG); avoid sizes above 2000 x 2000 or below 1000 x 1000 if full width, or half of each if half width
    - Always include alt text describing the content of the image
    - No space before, one space ("|") after if full width
    - Screenshot sourcing
   
    Writing (English):
    - Standard written US English; US spellings are nominally preferred for consistency but not strictly required, and existing spellings should be kept unless the portion of text is rewritten
    - AP style unless noted elsewhere here
    - Follow the [OpenStack General Writing Guidelines](https://docs.openstack.org/doc-contrib-guide/writing-style/general-writing-guidelines.html)
    - Maintain an explanatory rather than expository tone ("How" rather than "What")
        - "Spyder can do XXX." -> "To do XXX, you can..."
    - Focus on the user; this is documentation, not promotional material
    - Try to use simple language if possible and avoid buzzwords, jargon and acronyms
    - Avoid idioms and other constructs that might be unclear to non-native speakers
    - Make sure capitalization, spacing etc. of proper names and acronyms are correct and consistent
    - In text, use the full name for file types ("TIFF" and "JPEG", not "TIF" and "JPG"), and prefer "directory", over "folder"
    - Must use ISO 8601 (YYYY-MM-DD HH:MM:SS, 24-hour format, with leading zeros) for all numeric dates and times. No convention is imposed for textual forms (e.g. January 1, 2018; 1 April, 1995; etc) so long as all three components are provided, the month names are written out in full, and the year is written as 4 digits.
    - Must use ``.``, the period/point/full stop, as the decimal separator (e.g. pi is 3.14)
    - If a separator is used between groups of digits for readability, must be either the space or the comma
    - Should use only SI/metric for units