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
    # Download the git master version (developing version):

      cd $HOME/git/cWB
      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/>`__ and 
`Read the Docs Theme <https://sphinx-rtd-theme.readthedocs.io/en/latest/>`__


In CIT cluster it is possible to use the pre-installed libraries:  

   .. code-block:: bash

      # setting (for bash shell)

      source ~waveburst/virtualenv/pycwb/bin/activate

      # setting (for tcsh shell)

      source ~waveburst/virtualenv/pycwb/bin/activate.csh



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 pycwb virtual enviroment ~/virtualenv/pycwb

      # create pycwb virtual enviroment ~/virtualenv/pycwb

      python3 -m venv ~/virtualenv/pycwb

      # activate pycwb virtual enviroment

      source ~/virtualenv/pycwb/bin/activate

      # install packages into ~/virtualenv/pycwb

      pip3 install -r requirements.txt

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

      sphinx==1.8.1
      sphinxcontrib-programoutput
      matplotlib
      sphinx_rtd_theme
      sphinx-git
      sphinxcontrib-contentui
      sphinxcontrib-doxylink==1.6


      # to update packages in ~/virtualenv/pycwb

      pip3 install -r requirements.txt -U


      # setting (for bash shell)

      source ~/virtualenv/pycwb/bin/activate


      # setting (for tcsh shell)

      source ~/virtualenv/pycwb/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

     # include cWB command in the MANPATH environmental variable

       - setting (for bash shell)

         export MANPATH=~/git/cWB/documentation/_build:$MANPATH

       - setting (for tcsh shell)

         setenv MANPATH    "~/git/cWB/documentation/_build:$MANPATH" 

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

         man cwb_inet
   


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

To public the documentattion on web do: 

   .. code-block:: bash

      # create symbolic link in ~/public_html directory:

      mkdir ~/public_html/cwb  
      cd ~/public_html/cwb
      ln -s ~/git/cWB/documentation/_build/html documentation

      # at CIT it is available on web at the following link:

      https://ldas-jobs.ligo.caltech.edu/~user/cwb/documentation

      Ex: `https://ldas-jobs.ligo.caltech.edu/~waveburst/doc/cwb/xman`   

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

Here is a list of usefull 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**

   - `sphinx-git <http://sphinx-git.readthedocs.io/en/latest>`__
   - `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>`__
   - `Online Sphinx editor <https://livesphinx.herokuapp.com/>`__
   - `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/>`__