[doc] fixes

.github/workflows/upload_docs.yml

@@ -18,7 +18,7 @@ jobs:
         shell: bash -l {0}
         run: |
           cd doc/sphinx
-          make html
+          make html SPHINXOPTS="-W --keep-going"
       - name: Upload documentation
         shell: bash -l {0}
         if: github.ref == 'refs/heads/master'

doc/sphinx/source/ci/index.rst

@@ -6,7 +6,7 @@ Continuous integration and deployment
 The NNPDF code base makes use of externally hosted services, to aid development
 and testing. These are typically called *Continuous integration (CI)* or
 *Continuous deployment* services. Their main task is to execute automated tests
-on the code and produce :ref:`binary builds <conda>` which allow it to be
+on the code and produce :ref:`binary builds <conda-packages>` which allow it to be
 automatically deployed. The tests automatically run upon ``git push`` to any branch
 in the GitHub server (see :ref:`git <gitsection>`).
 
@@ -30,7 +30,7 @@ Our CI service works roughly as follows:
 
       - Compiling the code.
       - Running the tests.
-      - Possibly, uploading the compiled binaries and documentation to the :ref:`NNPDF server <server>`.
+      - For release tags, uploading the documentation to the :ref:`NNPDF server <server>`.
         We use `Conda-build <https://docs.conda.io/projects/conda-build/en/latest/>`_ to do much of the heavy lifting for these actions.
  3. The CI service reports whether it has *succeeded* or *failed* to the GitHub,
     server, which displays that information next to the relevant pull request or
@@ -61,9 +61,6 @@ them, do something like::
 
 The secrets are:
 
-  - ``NETRC_FILE`` a base64 encoded string containing a ``~/.netrc`` file with
-	  the :ref:`credentials <server-access>` to the private conda repository
-	  https://packages.nnpdf.science/conda-private/
   - ``NNPDF_SSH_KEY`` a base64 string containing a private SSH key which is
 	  authorized to access the :ref:`upload account of the NNPDF server <server-access>`.
 
@@ -107,5 +104,5 @@ Our GitHub Action service implements:
     commit. Some logs are generated, which can aid in determining the cause of errors.
  4. If the workflow succeeds, a comment to the initial pull request will appear with link references to the generated report and fit.
 
-The progress reports of the various jobs at `GitHub Actions <https://github.com/NNPDF/actions>`_, upon logging in
+The progress reports of the various jobs can be seen at the `NNPDF Github Actions <https://github.com/NNPDF/nnpdf/actions>`_, upon logging in
 with an authorized GitHub account.

doc/sphinx/source/conf.py

@@ -75,7 +75,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['modules/**']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
@@ -92,7 +92,7 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {"logo_only": True, "display_version": False}
+html_theme_options = {"logo_only": True}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

doc/sphinx/source/contributing/python-tools.rst

@@ -31,7 +31,7 @@ Python code can be evaluated interactively, which can speed up the development.
     environment running on the browser. Useful for bigger experiments.
 
 .. note::
-    When developing :ref:`validphys <validphys>` related code interactively, be
+    When developing :ref:`validphys <vp-index>` related code interactively, be
     sure to read about the :ref:`API functionality <vpapi>`.
 
 Testing
@@ -153,7 +153,7 @@ Before beginning you will need to ensure that you have the tests dependencies,
 which can be checked in :code:`nnpdf/conda-recipe/meta.yml`.
 
 The next step is to write the test function. It is highly recommended to use the
-:ref:`validphys API <api>` for this, both to simplify the code and to make it agnostic to the
+:ref:`validphys API <vpapi>` for this, both to simplify the code and to make it agnostic to the
 structure of backend providers - provided that they produce the same results. See
 for example a function which tests the ``plot_pdfs`` provider:
 

doc/sphinx/source/data/intro.rst

@@ -54,5 +54,5 @@ using these terms in this sense, they will be italicised for clarity.
 Dataset naming conventions
 --------------------------
 
-See :ref:`dataset_naming_convention` for a definition of how datasets should be
+See :ref:`dataset-naming-convention` for a definition of how datasets should be
 named.

doc/sphinx/source/external-code/pdf-codes.rst

@@ -1,4 +1,4 @@
-.. _lhapdf:
+.. _lhapdf-code:
 
 PDF set storage and interpolation
 =================================
@@ -23,7 +23,7 @@ alongside NNPDF, and so it therefore contains the features and settings required
 That is, it includes quark masses in the MSbar scheme, the various FONLL heavy quark schemes, scale
 variations up to NLO, etc. Note that at the time of writing, a more streamlined code is being
 written to replace APFEL, which is currently dubbed EKO ('Evolution Kernel Operator'). To find more
-general information about PDF evolution and the DGLAP equations, you can go to the :ref:`Theory section <thoery>`.
+general information about PDF evolution and the DGLAP equations, you can go to the :ref:`Theory section <theory>`.
 
 PDF compression
 ---------------

doc/sphinx/source/figuresofmerit/index.rst

@@ -1,5 +1,5 @@
 Chi square figures of merit
-================================================================================
+===========================
 
 Within the NNPDF methodology various figures of merit are used, each of which
 can be used in different situations. To avoid confusion, it is important to
@@ -13,7 +13,7 @@ when each of them is used.
 
 
 The basis of the loss functions: 𝜒²
---------------------------------------------------------------------------------
+-----------------------------------
 The :math:`\chi^2` figures of merit used in the NNPDF methodology are all
 based on the chi square statistic:
 
@@ -73,7 +73,7 @@ set, which needs to be specified.
 
 
 Missing higher order uncertainties
---------------------------------------------------------------------------------
+----------------------------------
 Another source of uncertainties that we may want to include in the covariance
 matrix are theoretical uncertainties, particularly missing higher order
 uncertainties estimated through scale variations. These uncertainties can be
@@ -84,7 +84,7 @@ covariance matrix'. A paper discussing the formalism can be found here:
 
 
 Future test: including PDF errors
---------------------------------------------------------------------------------
+----------------------------------
 To test the generalization power of the NNPDF fitting framework in the region
 where PDFs are not constrained by data, the 'future test' has been developed.
 The figure of merit considered in a future test is again the :math:`\chi^2`,
@@ -101,7 +101,7 @@ For a more detailed discussion of the future test formalism see e.g.
 .. _covmat-reg:
 
 Regularized covariance matrices
---------------------------------------------------------------------------------
+-------------------------------
 Information about the accuracy of the experimental uncertainty is generally not
 available, nevertheless inaccuracies in an experimental covariance matrix can
 lead to problems during optimization. Simply making a conservative estimate of
@@ -130,7 +130,7 @@ within NNPDF can be found in sections 4.2 and 8.7 of the NNPDF4.0 paper
 
 
 The weighted fit method
---------------------------------------------------------------------------------
+-----------------------
 To determine whether a specific dataset shows inconsistencies with the
 global dataset, one can produce a PDF determination in which that measurement
 is given an increased weight (usually equal to the combined weight of the other
@@ -159,7 +159,7 @@ HERACOMB_SIGMARED_C dataset to 100 by adding the following to the runcard:
 
 
 Experimental, validation, and training 𝜒²
---------------------------------------------------------------------------------
+-----------------------------------------
 When performing a PDF fit we generally distinguish three different definitions
 of the :math:`\chi^2` loss function, namely the experimental loss
 :math:`\chi^2_{\rm exp}`, the training loss :math:`\chi^2_{rm tr}` and the
@@ -180,6 +180,7 @@ of the neural network can be found in the :ref:`methodology overview
 
 
 .. _lagrange-multipliers:
+
 Positivity and integrability: Lagrange multipliers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Generally in an NNPDF fit we will want to ensure positivity and integrability of
@@ -198,7 +199,7 @@ while the analogous information for integrability can be found
 
 
 Hyperoptimized figure of merit
---------------------------------------------------------------------------------
+------------------------------
 To test the generalization power of a given methodology (a specific set of
 hyperparameter values), we employ hyperoptimization, specifically we use
 K-folds cross-validation. The idea of K-folds cross-validation is to create

doc/sphinx/source/get-started/installation.rst

@@ -67,7 +67,7 @@ In the case of conda, it defaults to ``${CONDA_PREFIX}/share/NNPDF``.
 It is possible to configure where to download theory and results using a ``nnprofile`` file as described in :ref:`nnprofile`.
 
 
-
+.. _docker:
 
 Using the code with docker
 --------------------------

doc/sphinx/source/n3fit/methodology.rst

@@ -127,8 +127,8 @@ provide a faster convergence to the solution.
 	Parameters like the number of layers, nodes, activation functions are hyper-parameters that require tuning.
 
 
-To see the structure of the model, one can use Keras's ``plot_model`` function as illustrated in the script below.
-See the `Keras documentation <https://www.tensorflow.org/api_docs/python/tf/keras/utils/plot_model>`_ for more details.
+To see the structure of the model, one can use Keras' ``plot_model`` function as illustrated in the script below.
+See the `this section of the Keras documentation <https://www.tensorflow.org/api_docs/python/tf/keras/utils/plot_model>`_ for more details.
 
 .. code-block:: python
 
@@ -206,10 +206,7 @@ Following the gradient descent approach the training is performed in iteration s
   descent update scheme (which controls the convergence step size and speed).
 
 The gradient descent schemes are usually controlled by the **learning rate**, and the total
-**number of iterations**. Examples of fits using the ``n3fit`` methodology are available here:
-
-- DIS-only fit based on NNPDF3.1 NNLO setup: `view <https://vp.nnpdf.science/KTzrle5FQGuuBdcigkDKnQ==/>`_
-- Global fit based on NNPDF3.1 NNLO setup: `view <https://vp.nnpdf.science/qtXzt-BbQZGkV6P4pf9-UA==/>`_
+**number of iterations**.
 
 .. important::
 	The gradient descent scheme (RMSprop, Adagrad, etc.), the learning rate, the number of iteractions are hyper-parameters that require tuning.

doc/sphinx/source/releases.rst

@@ -1,17 +1,19 @@
 .. _releases:
+
 Releases and compatibility policy
 =================================
 
 Development occur in the tip of the `master branch <https://github.com/NNPDF/nnpdf/tree/master>`_
 while we aim for this branch to be stable, tested and correct, this is not guaranteed.
 Premade packages are available for the latest tag
-:ref:`generated automatically<CI>` and can be :ref:`readily installed<conda>`.
+:ref:`generated automatically<CI>` and can be :ref:`readily installed <conda-packages>`.
 See the compatibility policy below. The
 main results, such as NNPDF 4.0 :cite:p:`nnpdf40` will be produced with a frozen
-:ref:`tag <tags>`, a :ref:`conda environment <conda>` and a :ref:`docker image
+:ref:`tag <tags>`, a :ref:`conda environment <conda-packages>` and a :ref:`docker image
 <docker>` so that they can be reproduced entirely.
 
 .. _tags:
+
 Tags
 ----
 
@@ -54,6 +56,7 @@ significant releases since the code was made public are:
     Used to produce the NNPDF 4.0 :cite:p:`nnpdf40` fits.
 
 .. _compatibility_policy:
+
 Compatibility Policy
 --------------------
 

doc/sphinx/source/serverconf/index.rst

@@ -8,7 +8,7 @@ meant for both public and internal consumption. It hosts the following URLs:
 
   - https://data.nnpdf.science: Hosts **public**
     NNPDF data such as PDF fits, releases etc.
-  - https://vp.nnpdf.science: Hosts the :ref:`validphys <vp-index>` 
+  - https://vp.nnpdf.science: Hosts the :ref:`validphys <vp-index>`
     report and displays an index of all of the reports.
   - https://wiki.nnpdf.science: Hosts the github wiki version.
   - https://packages.nnpdf.science/: Hosts the ``conda`` binary packages.
@@ -29,6 +29,7 @@ to the ``nnpdf@lxplus`` account at CERN.
 
 
 .. _server-access:
+
 Access
 ------
 
@@ -39,35 +40,22 @@ The access to the server is provided by
 ``ssh``/:ref:`vp-upload <upload>` with the following restrictions:
 
 - ``ssh`` access to ``root`` is forbidden.
-- There is a shared ``nnpdf`` user with low privileges. In order to login
-the user must send his public ssh key (usually in ``~/.ssh/id_rsa.pub``) to SC.
-The ``nnpdf`` is not allowed to login with password.
+- There is a shared ``nnpdf`` user with low privileges. In order to login the user must send his public ssh key (usually in ``~/.ssh/id_rsa.pub``) to JCM. This ``nnpdf`` user is not allowed to login with password.
 
 The ``nnpdf`` user shares a common ``/home/nnpdf`` folder where all NNPDF
-material is stored. Public access to data is available for all files
-in the ``/home/nnpdf/WEB`` folder. The ``validphys`` reports are stored in
-``/home/nnpdf/validphys-reports`` and the wiki in
-``/home/nnpdf/WEB/wiki``.
-
-Access for continuous deployment tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The :ref:`conda packages<conda>` as well as the documentation are
-automatically uploaded to the server by the Continous Integration service
-(Travis), through an user called ``dummy`` which has further reduction in
-privileges (it uses the ``rssh`` `shell <https://linux.die.net/man/1/rssh>`_ and it
-is only allowed to run the ``scp`` command. An accepted private key is stored
-securely in the :ref:`Travis configuration <travis-variables>`.  The packages
-are uploaded to ``/home/nnpdf/packages``.
+material is stored. Public access to data is available
+in the ``/home/nnpdf/WEB`` folder and the ``validphys`` reports are stored in
+``/home/nnpdf/validphys-reports``.
+
 
 HTTP access
 ~~~~~~~~~~~
 
-Tools such as :ref:`conda <conda>` and :ref:`vp-get<download>` require access to
+Tools such as the private :ref:`conda <conda-packages>` and :ref:`vp-get<download>` require access to
 private URLs, which are password-protected, using HTTP basic_auth. The
 access is granted by a ``/.netrc`` file containing the user and password
 for the relevant servers. The ``/.netrc`` file is typically generated
-at :ref:`installation<conda>` time. It should look similar to::
+at :ref:`installation <conda-packages>` time. It should look similar to::
 
   machine vp.nnpdf.science
       login nnpdf
@@ -157,9 +145,9 @@ Cron jobs
 The following cron jobs are registered for the ``nnpdf`` user:
 
 - every day at 4 AM run the ``index-email.py`` script.
-- at every reboot run ``index-reports.py``, ``index-fits.py``, ``index-hyperscan.py``, ``index-packahes-public.sh`` 
-  and ``index-packages-private.sh``, which monitor continuously the respective folders and create indexes that 
-  can be used by various applications. The first two are homegrown scripts (see :ref:`Web Scripts <web-scripts>`) 
+- at every reboot run ``index-reports.py``, ``index-fits.py``, ``index-hyperscan.py``, ``index-packahes-public.sh``
+  and ``index-packages-private.sh``, which monitor continuously the respective folders and create indexes that
+  can be used by various applications. The first two are homegrown scripts (see :ref:`Web Scripts <web-scripts>`)
   and the later two use `conda-index <https://docs.conda.io/projects/conda-build/en/latest/resources/commands/conda-index.html>`_.
 
 
@@ -170,6 +158,8 @@ The following cron jobs are registered for the ``root`` user:
 - reboot every Sunday at 6am (in order to use new kernels).
 - perform system update every day.
 
+.. _web-server:
+
 Web server Configuration
 ------------------------
 

doc/sphinx/source/theory/FastInterface.rst

@@ -72,8 +72,8 @@ using the (interpolated) DGLAP evolution operators,
     \begin{equation}
     f_{i,\beta \tau} = \sum_j \sum_{\alpha} \Gamma^{\tau}_{ij,\alpha \beta}\,f_j(x_{\alpha},Q_0^2) \, ,
     \end{equation}
-so that the nuclear DIS structure function can be
-evaluated as
+
+so that the nuclear DIS structure function can be evaluated as
 
 .. math::
 

doc/sphinx/source/theory/PTevol.rst

@@ -687,7 +687,7 @@ N space solutions to the evolution equations (Ref. )
 
     \binom{\Sigma}{g}(N,a_s) = \bigg[\mathbb{I}+\sum_{k=1}^{\infty}a_s^kU_k(N)\bigg] \mathbf{L}(a_s,a_0,N)\bigg[\mathbb{I}+\sum_{k=1}^{\infty}a_0^kU_k(N)\bigg]^{-1}\binom{\Sigma}{g}(N,a_0)\equiv \mathbf{\Gamma}_S(N,a_s,a_0)\binom{\Sigma}{g}(N,a_0)
 
--  The *fully truncated*\  [1]_ expression of the matrix evolution
+-  The *fully truncated* expression of the matrix evolution
    kernel up to NNLO reads
 
 .. math::
@@ -761,20 +761,20 @@ N space solutions to the evolution equations (Ref. )
 
 .. math::
 
-    \Gamma_{NS,LO}^{\pm,v}(N,a_s,a_0)= (\frac{a_s}{a_0})^{-R_0^{ns}}
+    \Gamma_{\rm NS,LO}^{\pm,v}(N,a_s,a_0)= (\frac{a_s}{a_0})^{-R_0^{ns}}
 
 -  Both iterated and truncated non-singlet solutions can be written down
    in a compact closed form at NLO as well. Iterated solution:
 
 .. math::
 
-    \Gamma^{\pm,v}_{NS,NLO}(N,a_s,a_0) =\exp\bigg{\frac{U^{\pm,v}_1} {b_1}\ln(\frac{1+b_1a_s}{1+b_1 a_0})\bigg}(\frac{a_s}{a_0})^{-R_0^{ns}}.
+    \Gamma^{\pm,v}_{\rm NS,NLO}(N,a_s,a_0) =\exp\bigg(\frac{U^{\pm,v}_1} {b_1}\ln(\frac{1+b_1a_s}{1+b_1 a_0})\bigg)(\frac{a_s}{a_0})^{-R_0^{ns}}.
 
 -  Truncated solution:
 
-$$\label{ns-sol0} \\Gamma^{\pm,v}_{\rm NS,NLO} (N,a_s,a_0)\: = \\:\left(
-1 - U_1^{\,\pm,v} (a_s - a_0) \\right) \\left( \\frac{a_s}{a_0}
-\\right)^{-R_0^{\:\!\rm ns}}.$$
+.. math::
+
+    \Gamma^{\pm,v}_{\rm NS,NLO}(N,a_s,a_0) = \left(1 - U_1^{\,\pm,v} (a_s - a_0) \right) \left( \frac{a_s}{a_0}\right)^{-R_0^{\:\!\rm ns}}.
 
 Getting back the x-space PDF’s
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/sphinx/source/tutorials/closuretest.rst

@@ -1,6 +1,5 @@
 .. _tut_closure:
 
-
 How to run a closure test
 =========================
 
@@ -46,6 +45,7 @@ The main obvious disadvantage is that a pre-existing PDF may not be a suitable
 proxy for the underlying law.
 
 .. _prep_ct_runcard:
+
 Preparing the closure test runcard
 ----------------------------------
 

doc/sphinx/source/tutorials/conda.rst

@@ -1,3 +1,5 @@
+.. _conda-packages:
+
 How to build conda-packages
 ---------------------------
 

doc/sphinx/source/tutorials/futuretests.rst

@@ -1,4 +1,5 @@
 .. _futuretests:
+
 How to run a Future Test
 ========================