Documentation
============================

General organization of documentation
----------------------------------------

Documentation is stored locally, on a separate branch of GEOP4TH git: the ``doc`` branch. Documentation is built from .rST files (see `Files to modify`_)
and manually updated. Once edits are pushed to the remote ``doc`` branch, the website containing online documentation is automatically generated on the Git through a CI pipeline. 

Install Python packages
-------------------------------

Before being able to modify the documentation, you should first install
the required modules:

.. tab-set:: 

   .. tab-item:: with conda
   
      In Anaconda Prompt::

        conda install git sphinx sphinx-rtd-theme pydata-sphinx-theme sphinx-tabs sphinx-multiversion sphinx-design sphinx-copybutton sphinx-togglebutton --channel conda-forge
   
   .. tab-item:: with mamba
   
      In Anaconda Prompt::
   
         mamba install git sphinx sphinx-rtd-theme pydata-sphinx-theme sphinx-tabs sphinx-multiversion sphinx-design sphinx-copybutton sphinx-togglebutton
   
   .. tab-item:: with pip
   
      ::

         pip install sphinx-rtd-theme sphinx-pydata-theme sphinx-tabs sphinx-design sphinx-copybutton sphinx-togglebutton


Files to modify
------------------

Documentation is written in the .rst (reStructuredText) files in the 📁 *geop4th/docs/readthedocs/source* folder.

`Here <https://bashtage.github.io/sphinx-material/rst-cheatsheet/rst-cheatsheet.html>`_ is a summary of rST syntax. Do not hesitate
also to click on *View page source* on the online GEOP4TH documentation!

You can finally push your changes on the ``doc`` branch :)

Update the documentation
----------------------------

One you have modified a file, you can navigate to the 📁 *geop4th/docs/readthedocs* folder and run *update_doc.bat*.



.. |IDE| raw:: html

  <abbr title="Integrated development environment">IDE</abbr>

.. # define a hard line break for HTML
.. |br| raw:: html

   <br>
   

.. |nbsp| unicode:: 0xA0 
   :trim: