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.
New documentation can be added in markdown, naming the source files with
the .md
suffix, or restructured text, with the .rst
suffix
formats.
Note
The md
format is now deprecated and only supported for legacy reasons.
The reStructured Text format natively supports equation displaying as well as
directives such as this note and is thus the preferred format for NNPDF
documentation. Despite this, it is possible to evaluate inline rst
in a
md
file using the eval_rst
command in legacy files written in
markdown.
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 the markdown or 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`
Useful Markdown and Restructured Text Tools
Various markdown and restructured text cheatsheets exist online.
In restructured text, a \(\LaTeX\) block can be generated using
.. math::
\frac{1}{2}
while inline maths is generated using
:math:`\frac{1}{2}`
with attention being brought to the backticks. Note: the markdown interpreter being used here does not support inline maths, so if formula dense documentation is being implemented, it is advised to use restructured text instead.
One can cross reference various parts of their markdown file using
anchors
, which provide clickable pieces of text which transport the
reader to a particular part of the document.
To do this: add an anchor point in the text. This may look like the following:
Lorem ipsum dolor sit amet <a name="label"</a> consectetur adipiscing elit, sed do
we can then jump to label
from an arbitrary point in the text by
using [text](#label)
As an example, clicking this will take the reader to the top of the page.
This was done by having the following lines of code:
For example, clicking [this](#top) will take the reader to the top of the page.
as well as
# NNPDF code and standards documentation <a name="top"></a>
at the top of this file.
In addition, one can link to other pages within the documentation by
[text](<relative-path-to-md-or-rst-file>.<extension>)
.
One can define “labels” for RestructuredText, which can be referred to from anywhere, like this:
.. _my-reference-label:
Section to cross-reference
--------------------------
This is the text of the section.
It refers to the section itself, see :ref:`my-reference-label`.
Such labels can also be defined in Markdown by using rst
syntax
embedded in code markers in markdown:
```eval_rst
.. _my-reference-label:
```
Labels can be linked to from anywhere using the syntax
[link text](my-reference-label)
for Markdown and
:ref:`my-reference-label`
for RestructuredText, as described in its documentation.
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