.. include:: images.rst

How to Contribute
------------------


Install Documentation
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

    # download cWB Documentation from GIT Repository
    # The suggested local directory where to download the repository is $HOME/git/cWB

      cd $HOME/git/cWB

    # PUBLIC git repository

      git clone https://gitlab.com/gwburst/documentation.git

    # LVK git repository

      git clone git@git.ligo.org:cWB/documentation.git


Documentation uses `doxygen <http://www.stack.nl/~dimitri/doxygen/>`__ to generate reference guide
for `cWB library <https://git.ligo.org/cWB/library>`__ and `cWB config <https://git.ligo.org/cWB/config>`__.
The instructions to install the library and config are `here <install.html#wat-installation>`__.


Install Auxiliary Libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The cWB documentation is written in `reStructuredText Format <http://docutils.sourceforge.net/rst.html>`__
and uses `Sphinx <http://www.sphinx-doc.org/en/master/>`__,
`Read the Docs Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>`__,
and `sphinx-multiversion <https://holzhaus.github.io/sphinx-multiversion/>`__ for versioned builds.


To install the auxiliary libraries in the local user account do:

   .. code-block:: bash

      # installation of packages used for cwb documentation
      # packages are installed into a virtual environment ~/virtualenv/cwb_docs

      # create the virtual environment

      python3 -m venv ~/virtualenv/cwb_docs

      # activate the virtual environment

      source ~/virtualenv/cwb_docs/bin/activate

      # install packages

      pip3 install -r requirements.txt

      # the requirements.txt file is in the documentation git repository:

      sphinx>=7.4,<8
      sphinx-multiversion>=0.2.4
      sphinx-rtd-theme>=3.0
      sphinxcontrib-programoutput>=0.17
      sphinxcontrib-contentui>=0.2.5
      sphinxcontrib-doxylink>=1.12
      matplotlib>=3.7


      # to update packages

      pip3 install -r requirements.txt -U


      # setting (for bash shell)

      source ~/virtualenv/cwb_docs/bin/activate


      # setting (for tcsh shell)

      source ~/virtualenv/cwb_docs/bin/activate.csh



Generate Documentation 
~~~~~~~~~~~~~~~~~~~~~~


   .. code-block:: bash

     # generate cWB config and library reference guides with Doxygen

     make doxygen

     # generate cWB documentation

     make html

     # generate cWB command man

     make man

     # the man1 files are copied into library $HOME_WAT/man directory

     # to get the online command help do (Ex):

         man cwb_inet
   

Public Documentation 
~~~~~~~~~~~~~~~~~~~~

| |cWB|

For more details on building and maintaining the documentation under public GitLab project pages, see

.. toctree::
    :maxdepth: 1

    build_gl_pages

   
Useful Links
~~~~~~~~~~~~

Here is a list of useful references to learn how to start with sphinx documentation.

 - **Main**

   - `Sphinx <http://www.sphinx-doc.org/en/master/>`__

 - **Themes**

   - `Sphinx Themes <https://sphinx-themes.org/>`__
   - `Read the Docs Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>`__
   - `TYPO3 Documentation <https://docs.typo3.org/>`__

 - **Extensions**

   - `Contentui <http://sphinxcontrib-contentui.readthedocs.io/en/latest/index.html>`__
   - `doxylink <https://pypi.org/project/sphinxcontrib-doxylink/1.6/#description>`__

 - **Guides** 

   - `Python Documentation Generator <http://www.sphinx-doc.org/en/master/>`__
   - `reStructuredText Primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
   - `Documenting Your Project Using Sphinx <https://pythonhosted.org/an_example_pypi_project/sphinx.html>`__
   - `Sphinx and RST syntax guide <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`__
   - `reStructuredText tool support <https://stackoverflow.com/questions/2746692/restructuredtext-tool-support>`__
   - `reStructuredText Format <http://docutils.sourceforge.net/rst.html>`__
   - `reStructuredText Directives <http://docutils.sourceforge.net/docs/ref/rst/directives.html>`__
   - `awesome-sphinxdoc <https://github.com/yoloseem/awesome-sphinxdoc#extensions>`__
   - `The Python Packaging Authority <https://www.pypa.io/en/latest/>`__

 - **Examples**

   - `PyCBC <http://pycbc.org/pycbc/latest/html/index.html>`__
   - `GPAW <https://wiki.fysik.dtu.dk/gpaw/index.html>`__
   - `Salish Sea MEOPAR <http://salishsea-meopar-docs.readthedocs.io/en/latest/index.html>`__
   - `MkDocs <https://mkdocs.readthedocs.io/en/stable/>`__