###################################################
Common operations
###################################################

..  _virtual_env_activate:

Virtual environment activation
=====================================

To activate the virtual environment 

.. code-block:: bash

    usr1@server:~/sphinx$ source .venv/bin/activate

The prompt should look like this

.. code-block:: bash

    (.venv) usr1@server:~/sphinx$ 


..  _virtual_env_deactivate:

Virtual environment deactivation
=====================================

To deactivate virutal environment execute the following

.. code-block:: bash

    (.venv) usr1@server:~/sphinx$ deactivate

The prompt that is displayed should now look like this 

.. code-block:: bash

    usr1@server:~/sphinx$ 



..  _build_project:

Build project (generate html files)
=====================================

To generate html files from source ``*.rst`` files execute the following

.. code-block:: bash

    (.venv) usr1@server:~/sphinx$ sphinx-build -M html docs/source/ docs/build/


..  _deploy_project:

Deploy project (copy html files on web server)
======================================================

The prompt that is displayed should now look like this 

.. code-block:: bash

    (.venv) usr1@server:~/sphinx$ cp -R -v docs/build/html /var/www/{website directory}/



Useful rst notations
======================================================

* **Reference Links :**

`Sphinx doc : https://www.sphinx-doc.org <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html/>`_ 

`Cheat sheets : https://bashtage.github.io/sphinx-material/rst-cheatsheet <https://bashtage.github.io/sphinx-material/rst-cheatsheet/rst-cheatsheet.html>`_ 

`reStructuredText Directives : https://docutils.sourceforge.io/docs/ref/rst <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`_ 


* **Syntax for parts, chapters, sections, etc...**

|

* **LEVEL 1** : # for parts with overline. 

The notation is the following :

``########################``

Your text here

``########################``

The resulting look-and-feel is the following : 

#####################
This is a part
#####################

|

* **LEVEL 2** : = for sections

The notation is the following :

``====================``

Your text here

``====================``

The resulting look-and-feel is the following : 


This is a section
====================

|

* **LEVEL 3** : - for subsections

The notation is the following :


Your text here

``------------------------``

The resulting look-and-feel is the following : 


This is a subsection
------------------------
 
|

* **LEVEL 4** : ^ for subsubsections


The notation is the following :


Your text here

``^^^^^^^^^^^^^^^^^^^^^^^^^^``

The resulting look-and-feel is the following : 


This is a subsubsection
^^^^^^^^^^^^^^^^^^^^^^^^^^

|

* **LEVEL 5** : asterix for chapters with overline

The notation is the following :

``********************``

Your text here

``********************``

The resulting look-and-feel is the following : 


********************
This is a chapter
********************

|

* **LEVEL 6** :  " for paragraphs

The notation is the following :



Your text here

``""""""""""""""""""""""``

The resulting look-and-feel is the following :


This is a paragraph
""""""""""""""""""""""

|

* **Syntax for horizontal break**

Horizontal break : multiple - 

------------


.. raw:: html

    <embed>
        <br/><br/>
    </embed>

* **Syntax to use tables :** 

.. list-table:: Title
   :widths: auto
   :header-rows: 1

   * - Heading row 1, column 1
     - Heading row 1, column 2
     - Heading row 1, column 3
   * - Row 1, column 1
     -
     - Row 1, column 3
   * - Row 2, column 1
     - Row 2, column 2
     - Row 2, column 3


* **Highlighting text**

*Standard text formatting*

emphasis : *emphasis*

strong – equivalent of **strong**

literal – equivalent of ``literal``



*admonition*

.. admonition:: Note

    This is a tests of how admonition is styled
    It contains multiple lines
    Like this


*General note*

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

   If note text runs over a line, make sure the lines wrap and are indented to
   the same level as the note tag. If formatting is incorrect, part of the note
   might not render in the HTML output.

   Notes can have more than one paragraph. Successive paragraphs must
   indent to the same level as the rest of the note.

*Warning*

.. warning::
    This is warning text. Use a warning for information the user must
    understand to avoid negative consequences.

    Warnings are formatted in the same way as notes. In the same way,
    lines must be broken and indented under the warning tag.



*attention*

.. attention::
    This is a tests of how attention is styled

*caution*

.. caution::
    This is a tests of how caution is styled


*danger*

.. danger::
    This is a tests of how danger is styled

*hint*

.. hint::
    This is a tests of how hint is styled

*important*

.. important::
    This is a tests of how important is styled

*tip*

.. tip::
    This is a tests of how important is styled