#####################################################################
Cheat Sheet
#####################################################################

.. _Brad Stancel: https://bradstancel.com/
.. |date| date:: %m/%d/%Y

:Authors: `Brad Stancel`_
:Created:  04/01/2020
:Modified: |date|

.. _doc-system-cheat-sheet:

*********************************************************************
ReSTructured Text Snippets
*********************************************************************

.. _doc-system-cheat-sheet-sections:

Section Snippets
=====================================================================

*When writing reStructuredText, it is important to put the sections in the below order.*

**Sections:**

* ``#`` with overline, for parts
* ``*`` with overline, for chapters
* ``=``, for sections
* ``-``, for subsections
* ``^``, for subsubsections
* ``"``, for paragraphs

|

.. _doc-system-cheat-sheet-links:

Link Snippets
=====================================================================
|

Internal Links
---------------------------------------------------------------------

**For linking within the same RST document WITHOUT using references, then do this:**::

    My Section Title
    =============================

    Some content here.

    ...later in the same file ...

    See `My Section Title`_

*NOTE - This approach is brittle and breaks if either of the text changes. It also does NOT work across files.*


**BETTER WAY - For linking within the same RST document use references:**

First, setup or find the reference to link to like this::

    .. _my-special-section:

Then reference it like this::

    :ref:`Custom Link Text about my section <my-special-section>`


|

External Links
---------------------------------------------------------------------

**For a direct URL link do something like this:**::

    `External Documentation Page - Say Github <https:/github.com>`_

**Reusable external link approach, you can use Sphinx's** ``extlinks`` **extension:**::

    .. extlink:: externaldocs
        :prefix: https//extern-docs.example.com/
        :name: External Docs

    :externaldocs:`path/to/page.html`

**Linking between Sphinx projects, use the** ``sphinx.ext.intersphinx`` **extension:**::

Add the necessary config to the ``conf.py`` after adding the extension to the ``conf.py``:

.. code-block:: python3

    intersphinx_mapping = {
        'linux': ('https://writings.bradstancel.com/linux-docs', None),
        'server-programs': ('https://writings.bradstancel.com/server-programs', None)
    }

    # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
    intersphinx_disabled_reftypes = ["*"]

**Now you can reference it this way using "doc":**::

    :docs:`path/to/page`


**For basic internal links, you can do this using "doc":**::

    :doc:`Custom Link Text <relative/path/to/another/rst/file/no/extension>`


**For linking to a reference (specific section of a document), then do this:**::

    :ref:`name-of-sphinx-reference`

or with custom text::

    :ref:`This is my custom text <name-of-sphinx-reference>`


**For linking to a reference in A SEPARATE Sphinx Documentation Project using Intersphinx do this:**::

    :ref:`My Custom Link Text <my-intersphinx-config-entry:my-ref-from-other-project>`

for instance, if you were to have an entry in the ``intersphinx_mapping`` like shown above called ``server-programs`` and you wanted to link to a reference in THAT Sphinx project called ``aws-cli-version`` it would then look something like this::

    :ref:`AWS CLI Info Link <server-programs:aws-cli-version>`


*The key is that to make this reference, BOTH PROJECTS must use the Intersphinx extension*


|
.. _doc-system-cheat-sheet-common:

Common Snippets
=====================================================================

**To create a reference / shortcut / anchor link to a section do this:**::

    .. _gnome-customizations:

**To create and assign a value to a reference do this:**::

    .. _Brad Stancel: https://bradstancel.com/
    or
    .. |date| date:: %m/%d/%Y

then use it like this::

    :Authors: `Brad Stancel`_
    :Created:  04/01/2020
    :Modified: |date|


**To make something downloadable do this:**::

    :download:`Password Policy Screenshot 1 <images/Screenshot_2020-06-17_14.26.48-Annotated.png>`

**Display an image do this:**::

    .. image:: images/Screenshot_2020-06-17_14.26.48-Annotated.png


**Show a Graphviz Diagram:**::

    .. graphviz:: files/roles.dot


**Show a PlantUML Diagram:**::

    .. uml:: files/critical-path.uml


**Show a Mermaid Diagram:**::

    .. mermaid:: files/acm-flow-diagram.mermaid


**To show a block of code or config do this:**::

    .. code-block:: bash

        sudo systemctl restart apache2.service


**To reference a shortcut / anchor link like the one above do this (can be a different file in the project):**::

    :ref:`Whatever I want the link to say here <gnome-customizations>`


**To do a literal include of a file do this:**::

    .. include:: files/Entire-TCP-Conversation-of-Query-Between-OpsInsights-and-Client-Database.txt
    :literal:


or something like this::

    .. literalinclude:: files/php
    :language: php
    :linenos:


**Reuse Content by Including a Shared File**::

    .. include:: ../shared/folder/filename.rst

Helpful if you are working on multiple projects, you can save entire topics in shared files, and include those files in multiple projects.


`For more details see here <https://sublime-and-sphinx-guide.readthedocs.io/en/latest/reuse.html#include-a-shared-file>`_


**To show a CSV File:**::

    .. csv-table:: Table Title
    :file: CSV file path and name
    :widths: 30, 70
    :header-rows: 1


**To show a block of SQL statements / code do this:**::

    .. code-block:: sql
        
        SELECT encrypt_option FROM sys.dm_exec_connections WHERE session_id = @@SPID;

**To create a WARNING Message do this:**::

    .. warning::

        My Warning Message and Text goes here.


**To create a NOTE Message do this:**::

    .. note::

    This is note text. Use a note for information you want the user to
    pay particular attention to.


**Use Conditional Text (Requires specifying something in Sphinx build/Makefile):**::

    .. only:: Internal

    Content to be included only in the internal version of the document.


`See this link for more details <https://sublime-and-sphinx-guide.readthedocs.io/en/latest/conditions.html#use-conditional-text>`_


**Create a Glossary:**::

    .. glossary::

        Sphinx
        Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages.


**Reference a Glossary Term using one of the below:**::

    :term:`Sphinx`

    or

    :term:`reStructuredText<RST>`


`See this link for more details <https://sublime-and-sphinx-guide.readthedocs.io/en/latest/glossary.html#create-a-glossary>`_



**To embed a YouTube video do this:**::

    .. youtube:: LSQNTZIPsvI

*This requires the ``sphinxcontrib.youtube`` Sphinx extension to be installed*

.. _cheat-sheet-sphinx-snippets:

*********************************************************************
Sphinx Snippets
*********************************************************************

**Some key things to do in the conf.py file are listed below.**

.. code-block:: linux-config

    # Add any Sphinx extension module names here, as strings. They can be
    # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
    # ones.
    extensions = [
        'sphinx_rtd_theme',
        'sphinxcontrib.youtube',
        'recommonmark',
        'sphinx.ext.extlinks',
        'sphinx.ext.graphviz',
        'sphinx.ext.intersphinx',
        'sphinxcontrib.plantuml',
        'sphinxcontrib.mermaid',
        'sphinx_copybutton'
    ]


    project = 'Ops Insights SOC 2, Security and Compliance Documentation'
    copyright = '2020, ProcessFast, LLC'
    author = 'ProcessFast, LLC'
    html_logo = '_static/_images/OpsInsights-Square-70x70.png'
    html_favicon = '_static/_images/favicon.ico'
    html_show_sourcelink = False



.. _doc-system-cheat-sheet-links:

******************************************************
Links and References - ReSTructured Text Usage
******************************************************

- `Literal Include Directive options <https://devopstutodoc.readthedocs.io/en/stable/documentation/doc_generators/sphinx/rest_sphinx/code/literalinclude/literalinclude.html>`_