How to Edit Documentation
============================

The following is a basic guide for editing the documentation for this project. The documentation is rendered using Sphinx_ documentation builder. This guide is intended to be a basic guide that will allow a contributer to start editing the documentation for the RAPIDS Pipeline. The first step is to install Sphinx.

Mac OS  

    - ``brew install sphinx-doc``

Linux (Ubuntu)

    - ``apt-get install python3-sphinx``

Sphinx is a tool that translates a set of reStructuredText_ source files into various output formats such as HTML and PDF, automatically producing cross-references, indices, etc. The following is a basic outline of structure of Sphinx workspace and the syntax of reStructuredText.

Sphinx Workspace Structure
----------------------------

All of the files concerned with documentation can be found in the ``docs`` directory. At the top level there is the ``conf.py`` file and an ``index.rst`` file among others. There should be no need to change the ``conf.py`` file. The ``index.rst`` file is known as the master document and defines the document structure of the documentation (i.e. Menu Or Table of Contents structure). It contains the root of the “table of contents" tree -or toctree- that is used to connect the multiple files to a single hierarchy of documents. The TOC is defined using the ``toctree`` directive which is used as follows::

    .. toctree::
       :maxdepth: 2
       :caption: Getting Started

        usage/introduction
        usage/installation

The ``toctree`` inserts a TOC tree at the current location using the individual TOCs of the documents given in the directive command body. In other words if there are ``toctree`` directives in the files listed in the above example it will also be applied to the resulting TOC. Relative document names (not beginning with a slash) are relative to the document the directive occurs in, absolute names are relative to the source directory. Thus in the example above the ``usage`` directory is relative to the ``index.rst`` page . The ``:maxdepth:`` parameter defines the depth of the tree for that particular menu. The ``caption`` parameter is used to give a caption for that menu tree at that level. It should be noted the titles for the links of the menu items under that header would be taken from the titles of the referenced document. For example the menu item title for ``usage/introduction`` is taken from the main header specified in ``introduction.rst`` document in the ``usage`` directory. Also note the document name does not include the extention (i.e. .rst).

Thus the directory structure for the above example is shown below::

    ├── index.rst
    └── usage
        ├── introduction.rst
        └── installation.rst

Once the ``index.rst`` has been editted and content has been added and/or editted the documentation is built using the following command::

    $ make dirhtml

This command creates the ``_build`` directory which contains the generated HTML files of the documentation. It shoould be noted that once you have pushed your change to the repository the changes will be published even if you have not run ``make dirhtml``


Basic reStructuredText Syntax
-------------------------------

Now we will look at some basic reStructuredText syntax necessary to start editing the .rst files that are used to generate documentation. 

Headers
""""""""

**Section Header**

The following was used to make the header at the top of this page:
::

    How to Edit Documentation
    ==========================

**Subsection Header**

The follwoing was used to create the secondary header (e.g. Sphinx Workspace Structure section header)
::

    Sphinx Workspace structure
    ----------------------------

..... 


Lists
""""""
**Bullets List**
::

    - This is a bullet
    - This is a bullet

Will produce the following:

- This is a bullet
- This is a bullet


**Numbered List**
::

    #. This is a numbered list item
    #. This is a numbered list item

Will produce the following:

#. This is a numbered list item
#. This is a numbered list item

.....

Inline Markup
""""""""""""""
**Emphasis/Italics**
::

    *This is for emphasis*

Will produce the following 

*This is for emphasis*


**Bold**
::

    **This is bold text**

Will produce the following

**This is bold text**

..... 

**Code Sample**
::
    
    ``Backquotes = code sample``

Will produce the following:

``Backquotes = code sample``

**Apostraphies in Text**
::

    `don't know`

Will produce the following

`don't know`


**Literal blocks**

Literal code blocks are introduced by ending a paragraph with the special marker ``::``. The literal block must be indented (and, like all paragraphs, separated from the surrounding ones by blank lines)::

    This is a normal text paragraph. The next paragraph is a code sample::

        It is not processed in any way, except
        that the indentation is removed.

        It can span multiple lines.

    This is a normal text paragraph again.


The following is produced:

.....

This is a normal text paragraph. The next paragraph is a code sample::

    It is not processed in any way, except
    that the indentation is removed.

    It can span multiple lines.

This is a normal text paragraph again.

.....

**Doctest blocks**

Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They do not require the literal blocks syntax. The doctest block must end with a blank line and should not end with with an unused prompt:

>>> 1 + 1
2

**External links**

Use ```Link text <https://domain.invalid/>`_`` for inline web links `Link text <https://domain.invalid/>`_. If the link text should be the web address, you don’t need special markup at all, the parser finds links and mail addresses in ordinary text. *Important:* There must be a space between the link text and the opening ``<`` for the URL.

You can also separate the link and the target definition , like this
::

    This is a paragraph that contains `a link`_.

    .. _a link: https://domain.invalid/


Will produce the following:

This is a paragraph that contains `a link`_.

.. _a link: https://domain.invalid/



**Internal links**

Internal linking is done via a special reST role provided by Sphinx to cross-reference arbitrary locations. For this to work label names must be unique throughout the entire documentation. There are two ways in which you can refer to labels:

- If you place a label directly before a section title, you can reference to it with ``:ref:`label-name```. For example::

    .. _my-reference-label:

    Section to cross-reference
    --------------------------

    This is the text of the section.

    It refers to the section itself, see :ref:`my-reference-label`.

The ``:ref:`` role would then generate a link to the section, with the link title being “Section to cross-reference”. This works just as well when section and reference are in different source files. The above produces the following:

.....

.. _my-reference-label:

Section to cross-reference
"""""""""""""""""""""""""""

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

.....

- Labels that aren’t placed before a section title can still be referenced, but you must give the link an explicit title, using this syntax: ``:ref:`Link title <label-name>```.


**Comments**

Every explicit markup block which isn’t a valid markup construct is regarded as a comment. For example::

    .. This is a comment.

Go to Sphinx_ for more documentation. 

.. _Sphinx: https://www.sphinx-doc.org
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html