Adding to the Documentation

The NNPDF documentation is produced by the sphinx resource. To generate the sphinx documentation, navigate to the nnpdf/doc/sphinx/ directory and execute the command make html, ensuring one is inside the appropriate nnpdf conda environment. This produces the documentation in the build/index/ directory. The index.html can be viewed with any appropriate browser.

To add a new section to the documentation, create an appropriately named directory in the sphinx/source/ directory. Inside the new directory, add all relevant documentation in restructured text formats. In addition to these files, create an index.rst file containing:

Chapter Name
============

.. toctree::
   :maxdepth: 1

   ./file1.md
   ./file2.rst

ensuring that the number of = signs is the same as the number of characters in Chapter Name.

The next step is to reference the newly made index.rst in the main sphinx/source/index.rst file:

.. NNPDF documentation master file, created by
   sphinx-quickstart on Mon Oct 29 10:53:50 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

NNPDF documentation
===================

.. toctree::
   :maxdepth: 2

   get-started/index
   theory/index
   vp/index
   code/index
   tutorials/index
   QA/index
   <NEW CHAPTER>/index

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Adding BibTeX references

The documentation build supports BibTeX references via the sphinxcontrib-bibtex extension. Citations in the BibTeX format are added to the references.bib file in the Sphinx source directory. For example a citation like

@article{Carrazza:2016htc,
    author = "Carrazza, Stefano and Forte, Stefano and Kassabov, Zahari and Rojo, Juan",
    title = "{Specialized minimal PDFs for optimized LHC calculations}",
    eprint = "1602.00005",
    archivePrefix = "arXiv",
    primaryClass = "hep-ph",
    reportNumber = "CERN-PH-TH-2015-243, TIF-UNIMI-2015-13, OUTP-15-24P",
    doi = "10.1140/epjc/s10052-016-4042-8",
    journal = "Eur. Phys. J. C",
    volume = "76",
    number = "4",
    pages = "205",
    year = "2016"
}

can be appended to the refererences.bib file.

References can be added to RST documents using some variation of the cite role. For example :cite:p:`<BibTeX ID>` adds a parenthetical reference, and the above article can be cited using :cite:p:`Carrazza:2016htc`.

Adding indices for modules

Sphinx has the capability of automatically documenting any python package. It produces these under the index and module index sections. The functions and modules are documented using their corresponding docstrings.

To add a new module to document, add a new line in sphinx/Makefile under:

%: Makefile
    @if test $@ != "clean"; then
            sphinx-apidoc -o ./source/modules/validphys ../../validphys2/src/validphys/ ; \
            sphinx-apidoc -o ./source/modules/<MODULE-NAME> <PATH-TO-MODULE>  ;\
    fi