Merge pull request #418 from UCL-CCS/dpc/improve-docs

improve the documentation, adding in a reference to Diana's paper
UCL-CCS · Jun 27, 2024 · b2810f1 · b2810f1
2 parents 5d4a4ca + 0afba86
commit b2810f1
Show file tree

Hide file tree

Showing 16 changed files with 18 additions and 9 deletions.
diff --git a/docs/source/old/basic_tutorial.rst → docs/attic/doc/source/old/basic_tutorial.rst b/docs/source/old/basic_tutorial.rst → docs/attic/doc/source/old/basic_tutorial.rst
diff --git a/docs/source/old/cooling_coffee_cup.rst → ...tic/doc/source/old/cooling_coffee_cup.rst b/docs/source/old/cooling_coffee_cup.rst → ...tic/doc/source/old/cooling_coffee_cup.rst
diff --git a/docs/source/old/custom_encoder.rst → docs/attic/doc/source/old/custom_encoder.rst b/docs/source/old/custom_encoder.rst → docs/attic/doc/source/old/custom_encoder.rst
diff --git a/docs/source/old/dask_tutorial.rst → docs/attic/doc/source/old/dask_tutorial.rst b/docs/source/old/dask_tutorial.rst → docs/attic/doc/source/old/dask_tutorial.rst
diff --git a/docs/source/old/fusion_tutorial.rst → .../attic/doc/source/old/fusion_tutorial.rst b/docs/source/old/fusion_tutorial.rst → .../attic/doc/source/old/fusion_tutorial.rst
diff --git a/.../source/old/hier_sparse_grid_tutorial.rst → .../source/old/hier_sparse_grid_tutorial.rst b/.../source/old/hier_sparse_grid_tutorial.rst → .../source/old/hier_sparse_grid_tutorial.rst
diff --git a/docs/source/old/mcmc.rst → docs/attic/doc/source/old/mcmc.rst b/docs/source/old/mcmc.rst → docs/attic/doc/source/old/mcmc.rst
diff --git a/docs/source/old/multiencoder_tutorial.rst → .../doc/source/old/multiencoder_tutorial.rst b/docs/source/old/multiencoder_tutorial.rst → .../doc/source/old/multiencoder_tutorial.rst
diff --git a/docs/source/old/multisampler_tutorial.rst → .../doc/source/old/multisampler_tutorial.rst b/docs/source/old/multisampler_tutorial.rst → .../doc/source/old/multisampler_tutorial.rst
diff --git a/docs/source/old/relocate.rst → docs/attic/doc/source/old/relocate.rst b/docs/source/old/relocate.rst → docs/attic/doc/source/old/relocate.rst
diff --git a/docs/source/old/tutorials.rst → docs/attic/doc/source/old/tutorials.rst b/docs/source/old/tutorials.rst → docs/attic/doc/source/old/tutorials.rst
diff --git a/docs/source/old/validate_similarities.rst → .../doc/source/old/validate_similarities.rst b/docs/source/old/validate_similarities.rst → .../doc/source/old/validate_similarities.rst
diff --git a/docs/source/old/workflow_changes.rst → ...attic/doc/source/old/workflow_changes.rst b/docs/source/old/workflow_changes.rst → ...attic/doc/source/old/workflow_changes.rst
diff --git a/docs/source/concepts.rst b/docs/source/concepts.rst
@@ -62,18 +62,18 @@ central location where all information about your campaign is
 kept. The `Campaign` handles all validation and is transfers
 information between each stage of the workflow.
 
-The `Basic Tutorial <https://github.com/UCL-CCS/EasyVVUQ/blob/dev/tutorials/basic_tutorial.ipynb>`_
+The `Basic Tutorial <https://github.com/UCL-CCS/EasyVVUQ/blob/dev/tutorials/basic_tutorial.ipynb>`_ (link to repository) or `Basic Tutorial Binder <https://mybinder.org/v2/gh/UCL-CCS/EasyVVUQ/a6852d6c5ba36f15579e601d7a8d074505f31084?filepath=tutorials%2Fbasic_tutorial.ipynb>`_ (link to Binder to directly run the notebook) 
 gives a good hands-on introduction to defining parameters and 
 creating a campaign.
 
+
 Elements
 --------
 
 Within VECMA software components that can be reused in a wide range of
 application scenarios are known as ``Elements``.
 Within EasyVVUQ we provide five classes of ``Elements`` (:ref:`samplers`,
-:ref:`decoders`, :ref:`encoders`, and those providing :ref:`collation`,
-for the aggregation step, and :ref:`analysis` functionality) which we 
+:ref:`decoders`, :ref:`encoders`, and :ref:`analysis` functionality) which we 
 describe below.
 
 .. _samplers:
@@ -89,7 +89,7 @@ They deal with generic information in the sense that all parameters use the
 nomenclature and units provided by the user rather than anything specific to
 any application or workflow.
 
-Detailed information on the Sampler modules is available `here <https://easyvvuq.readthedocs.io/en/dev/_autodoc/easyvvuq.sampling.html>`_.
+Detailed information on the Sampler modules is available :doc:`here <_autodoc/easyvvuq.sampling>`.
 
 .. _encoders:
 
@@ -107,7 +107,7 @@ generic Encoder base class is picked up and may be used.
 This enables EasyVVUQ to be easily extended for new applications by 
 experienced users.
 
-Detailed information on the Encoder modules is available `here <https://easyvvuq.readthedocs.io/en/dev/_autodoc/easyvvuq.encoders.html>`_.
+Detailed information on the Encoder modules is available :doc:`here <_autodoc/easyvvuq.encoders>`.
 
 .. _decoders:
 
@@ -121,7 +121,7 @@ facilitate analysis of a wide range of applications.
 
 The `Encoder-Decoder tutorial <https://github.com/UCL-CCS/EasyVVUQ/blob/dev/tutorials/encoder_decoder_tutorial.ipynb>`_
 provides a good introduction to using Encoders and Decoders within EasyVVUQ. Detailed information on the Decoder modules
-themselves is available `here <https://easyvvuq.readthedocs.io/en/dev/_autodoc/easyvvuq.decoders.html>`_.
+themselves is available :doc:`here <_autodoc/easyvvuq.decoders>`.
 
 .. _analysis:
 
@@ -133,5 +133,11 @@ on the simulation output across a range of runs.
 Different types of analysis (for example bootstrapping of multiple runs from
 varied initial conditions) are, or will be,  provided by EasyVVUQ.
 
-Detailed information on the Analysis modules is available `here <https://easyvvuq.readthedocs.io/en/dev/_autodoc/easyvvuq.analysis.html>`_
+Detailed information on the Analysis modules is available :doc:`here <_autodoc/easyvvuq.analysis>`.
+
+.. _execution:
+
+Execution
+---------
 
+Some more information on the use of QCG-Pilothob can be found :doc:`here <QCG-PilotJob-EasyVVUQ>`.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -12,12 +12,12 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('easyvvuq'))
+sys.path.insert(0, os.path.abspath('../..'))
 
 from sphinx.ext.apidoc import main as apidoc_main
 apidoc_main(["--force", "-o", "./_autodoc", "../../easyvvuq"])
 
-autodoc_mock_imports = ['dill']
+autodoc_mock_imports = ['dill', 'SALib']
 
 # -- Project information -----------------------------------------------------
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -11,6 +11,8 @@ and uncertainty quantification (VVUQ) for a wide variety of simulations.
 It was conceived and developed within the EU funded `VECMA <http://www.vecma.eu/>`_ 
 (Verified Exascale Computing for Multiscale Applications) project.
 
+A good introduction can be found in the paper by D. Suleimenova *et al.*, “Tutorial applications for Verification, Validation and Uncertainty Quantification using VECMA toolkit”, J. Comput. Sci. 53, 101402 (2021), `DOI:10.1016/j.jocs.2021.101402 <https://doi.org/10.1016/j.jocs.2021.101402>`_.
+
 .. _goals:
 
 Goals
@@ -57,3 +59,4 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+* :doc:`_autodoc/modules`