From de2f7cf3a9b422bb1c5e2fc0fea8a1a08132ec9b Mon Sep 17 00:00:00 2001
From: Hu Zhao <zhao@mbd.rwth-aachen.de>
Date: Tue, 29 Nov 2022 16:35:19 +0100
Subject: [PATCH] docs: set up doc structure
---
docs/Makefile | 6 +-
docs/conduct.md | 2 -
docs/examples/emulator/README.rst | 2 +
docs/examples/inference/README.rst | 2 +
docs/examples/sampler/README.rst | 2 +
docs/examples/sensitivity/README.rst | 2 +
docs/examples/simulator/README.rst | 2 +
docs/index.md | 11 ---
docs/requirements.txt | 7 +-
docs/{changelog.md => source/changelog.rst} | 0
docs/{ => source}/conf.py | 50 ++++++++--
docs/source/emulator/index.rst | 0
docs/source/emulator/robustgasp.rst | 0
docs/source/index.rst | 104 ++++++++++++++++++++
docs/source/inference/active_learning.rst | 0
docs/source/inference/bayes_inference.rst | 1 +
docs/source/inference/index.rst | 0
docs/source/refs.bib | 0
docs/source/sampler/index.rst | 0
docs/source/sampler/latin.rst | 0
docs/source/sampler/metropolis_hastings.rst | 0
docs/source/sampler/saltelli.rst | 0
docs/source/sensitivity/index.rst | 0
docs/source/sensitivity/sobol.rst | 0
docs/source/simulator/index.rst | 0
docs/source/simulator/mass_point_model.rst | 0
docs/source/simulator/ravaflow24.rst | 0
docs/source/simulator/run_simulator.rst | 0
28 files changed, 165 insertions(+), 26 deletions(-)
delete mode 100644 docs/conduct.md
create mode 100644 docs/examples/emulator/README.rst
create mode 100644 docs/examples/inference/README.rst
create mode 100644 docs/examples/sampler/README.rst
create mode 100644 docs/examples/sensitivity/README.rst
create mode 100644 docs/examples/simulator/README.rst
delete mode 100644 docs/index.md
rename docs/{changelog.md => source/changelog.rst} (100%)
rename docs/{ => source}/conf.py (62%)
create mode 100644 docs/source/emulator/index.rst
create mode 100644 docs/source/emulator/robustgasp.rst
create mode 100644 docs/source/index.rst
create mode 100644 docs/source/inference/active_learning.rst
create mode 100644 docs/source/inference/bayes_inference.rst
create mode 100644 docs/source/inference/index.rst
create mode 100644 docs/source/refs.bib
create mode 100644 docs/source/sampler/index.rst
create mode 100644 docs/source/sampler/latin.rst
create mode 100644 docs/source/sampler/metropolis_hastings.rst
create mode 100644 docs/source/sampler/saltelli.rst
create mode 100644 docs/source/sensitivity/index.rst
create mode 100644 docs/source/sensitivity/sobol.rst
create mode 100644 docs/source/simulator/index.rst
create mode 100644 docs/source/simulator/mass_point_model.rst
create mode 100644 docs/source/simulator/ravaflow24.rst
create mode 100644 docs/source/simulator/run_simulator.rst
diff --git a/docs/Makefile b/docs/Makefile
index 2326b82..b881cfe 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -4,9 +4,9 @@
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS =
-SPHINXBUILD = python -msphinx
-SOURCEDIR = .
-BUILDDIR = _build
+SPHINXBUILD = sphinx-build
+SOURCEDIR = source
+BUILDDIR = source/_build
# Put it first so that "make" without argument is like "make help".
help:
diff --git a/docs/conduct.md b/docs/conduct.md
deleted file mode 100644
index 0568705..0000000
--- a/docs/conduct.md
+++ /dev/null
@@ -1,2 +0,0 @@
-```{include} ../CONDUCT.md
-```
\ No newline at end of file
diff --git a/docs/examples/emulator/README.rst b/docs/examples/emulator/README.rst
new file mode 100644
index 0000000..2665689
--- /dev/null
+++ b/docs/examples/emulator/README.rst
@@ -0,0 +1,2 @@
+emulator Examples
+^^^^^^^^^^^^^^^^^
\ No newline at end of file
diff --git a/docs/examples/inference/README.rst b/docs/examples/inference/README.rst
new file mode 100644
index 0000000..5fff070
--- /dev/null
+++ b/docs/examples/inference/README.rst
@@ -0,0 +1,2 @@
+inference Examples
+^^^^^^^^^^^^^^^^^^
\ No newline at end of file
diff --git a/docs/examples/sampler/README.rst b/docs/examples/sampler/README.rst
new file mode 100644
index 0000000..973f8dd
--- /dev/null
+++ b/docs/examples/sampler/README.rst
@@ -0,0 +1,2 @@
+sampler Examples
+^^^^^^^^^^^^^^^^
\ No newline at end of file
diff --git a/docs/examples/sensitivity/README.rst b/docs/examples/sensitivity/README.rst
new file mode 100644
index 0000000..6ab26a0
--- /dev/null
+++ b/docs/examples/sensitivity/README.rst
@@ -0,0 +1,2 @@
+sensitivity Examples
+^^^^^^^^^^^^^^^^^^^^
\ No newline at end of file
diff --git a/docs/examples/simulator/README.rst b/docs/examples/simulator/README.rst
new file mode 100644
index 0000000..fe4eb0f
--- /dev/null
+++ b/docs/examples/simulator/README.rst
@@ -0,0 +1,2 @@
+simulator Examples
+^^^^^^^^^^^^^^^^^^
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index e3acefa..0000000
--- a/docs/index.md
+++ /dev/null
@@ -1,11 +0,0 @@
-```{include} ../README.md
-```
-
-```{toctree}
-:maxdepth: 1
-:hidden:
-
-changelog.md
-conduct.md
-autoapi/index
-```
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 7b5bd2a..3dadde5 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
-myst-nb
-sphinx-autoapi
-sphinx-rtd-theme
\ No newline at end of file
+sphinx_rtd_theme
+sphinx_autodoc_typehints
+sphinxcontrib_bibtex
+sphinx_gallery
\ No newline at end of file
diff --git a/docs/changelog.md b/docs/source/changelog.rst
similarity index 100%
rename from docs/changelog.md
rename to docs/source/changelog.rst
diff --git a/docs/conf.py b/docs/source/conf.py
similarity index 62%
rename from docs/conf.py
rename to docs/source/conf.py
index db3af8c..64f3ff8 100644
--- a/docs/conf.py
+++ b/docs/source/conf.py
@@ -10,9 +10,9 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../src/psimpy/'))
# -- Project information -----------------------------------------------------
@@ -20,20 +20,37 @@
project = 'psimpy'
copyright = '2022, Hu Zhao'
author = 'Hu Zhao'
+#release = "v0.2.0"
# -- General configuration ---------------------------------------------------
+source_suffix = {
+ '.rst': 'restructuredtext',
+ '.md': 'markdown',
+}
+
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
- 'myst_nb',
- 'autoapi.extension',
+ # 'myst_nb',
+ # 'autoapi.extension',
+ 'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
+ 'sphinx_autodoc_typehints',
+ 'sphinx_gallery.gen_gallery',
+ 'sphinxcontrib.bibtex',
]
-autoapi_dirs = ['../src']
+
+# autoapi_dirs = ['../src']
+autoclass_content = 'init'
+autodoc_member_order = 'bysource'
+add_module_names = False
+
+bibtex_bibfiles = ['refs.bib']
+bibtex_default_style = 'unsrt'
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -44,6 +61,25 @@ templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# configure Sphinx-Gallery
+sphinx_gallery_conf = {
+ "examples_dirs": [
+ "../examples/emulator",
+ "../examples/inference",
+ "../examples/sampler",
+ "../examples/sensitivity",
+ "../examples/simulator",
+ ], # path to your example scripts,
+ "gallery_dirs": [
+ "../auto_examples/emulator",
+ "../auto_examples/inference",
+ "../auto_examples/sampler",
+ "../auto_examples/sensitivity",
+ "../auto_examples/simulator",
+ ], # path to where to save gallery generated output
+}
+
+
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -54,4 +90,4 @@ html_theme = 'sphinx_rtd_theme'
# 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,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
\ No newline at end of file
+html_static_path = ['_static']
diff --git a/docs/source/emulator/index.rst b/docs/source/emulator/index.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/emulator/robustgasp.rst b/docs/source/emulator/robustgasp.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..c07645b
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,104 @@
+:gitlab_url: https://git-ce.rwth-aachen.de/mbd/psimpy
+
+=======
+Welcome
+=======
+
+PSimPy (Predictive and probabilistic simulation with Python) implements
+a Gaussian process emulation-based framework that enables systematically and
+efficiently performing uncertainty-related analyses of physics-based
+models, which are often computationlly expensive. Examples are variance-based
+global sensitvity analysis, uncertainty quantification, and parameter
+calibration.
+
+
+Installation
+============
+
+:py:mod:`PSimPy` is a pure Python package. All Python-related dependencies are
+automatically taken care of. It should be noted that some modules rely on or use
+non-Python package and software. More specifically, the emulator module
+:py:mod:`robustgasp.py` relies on the R package
+`RobustGaSP <https://cran.r-project.org/web/packages/RobustGaSP/>`_;
+the simulator module :py:mod:`ravaflow24.py` relies on the open source software
+`r.avaflow 2.4 <https://www.landslidemodels.org/r.avaflow/>`_.
+
+If the simulator module :py:mod:`ravaflow24.py` is desired, you may follow the
+official `r.avaflow User manual <https://www.landslidemodels.org/r.avaflow/manual.php>`_
+to install it. The installation of the R package `RobustGaSP` is covered in
+following steps.
+
+We recommond you to install :py:mod:`PSimPy` in a virtual environment such as a
+`conda` environment. You may want to first install `Anaconda` or `Miniconda` if you
+haven't. The steps afterwards are as follows.
+
+1. Create a conda environment with Python 3.9::
+
+ conda create --name your_env_name python=3.9
+
+2. Install `R` if you don't have it on your machine (if you have `R`, you can
+ skip this step; alternatively, you can still follow this step to install `R` in
+ the conda environment)::
+
+ conda activate your_env_name
+ conda install -c conda-forge r-base=3.6
+
+3. Install the R package `RobustGaSP` in the R terminal::
+
+ R
+ install.packages("RobustGaSP",repos="https://cran.r-project.org",version="0.6.4")
+
+ Try if it is successfully installed by::
+
+ library("RobustGaSP")
+
+4. Configure the environment variable `R_HOME` so that `rpy2` knows where to find
+ `R` packages. You can find your `R_HOME` by typing the following command in the
+ R terminal::
+
+ R.home()
+ q()
+
+ It is a path like ".../lib/R". Set the environment variable `R_HOME` in your
+ conda environment by::
+
+ conda env config vars set R_HOME=your_R_HOME
+
+ Afterwards reactivate your conda environment to make the change take effect by::
+
+ conda deactivate
+ conda activate your_env_name
+
+5. Install :py:mod:`PSimPy` using `pip` in your conda environment by::
+
+ conda install -c conda-forge pip
+ pip install psimpy
+
+Now you should have :py:mod:`PSimPy` and its dependencies successfully installed
+in your conda environment. You can use it in the Python terminal or in your
+Python IDE.
+
+If you would like to use it with Jupyter Notebook (iPython Notebook), there is
+one extra step needed to set your conda environment on your Notebook:
+
+6. Install `ipykernel` and install a kernel that points to your conda environment
+ by::
+
+ conda install -c conda-forge ipykernel
+ python -m ipykernel install --user --name=your_env_name
+
+Now you can start your Notebook, change the kernel to your conda environment, and
+use :py:mod:`PSimPy`.
+
+
+.. toctree::
+ :hidden:
+
+ Home <self>
+ /emulator/index
+ /inference/index
+ /sampler/index
+ /sampling/index
+ /sensitivity/index
+ /simulator/index
+ refs.rst
diff --git a/docs/source/inference/active_learning.rst b/docs/source/inference/active_learning.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/inference/bayes_inference.rst b/docs/source/inference/bayes_inference.rst
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/docs/source/inference/bayes_inference.rst
@@ -0,0 +1 @@
+
diff --git a/docs/source/inference/index.rst b/docs/source/inference/index.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/refs.bib b/docs/source/refs.bib
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/sampler/index.rst b/docs/source/sampler/index.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/sampler/latin.rst b/docs/source/sampler/latin.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/sampler/metropolis_hastings.rst b/docs/source/sampler/metropolis_hastings.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/sampler/saltelli.rst b/docs/source/sampler/saltelli.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/sensitivity/index.rst b/docs/source/sensitivity/index.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/sensitivity/sobol.rst b/docs/source/sensitivity/sobol.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/simulator/index.rst b/docs/source/simulator/index.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/simulator/mass_point_model.rst b/docs/source/simulator/mass_point_model.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/simulator/ravaflow24.rst b/docs/source/simulator/ravaflow24.rst
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/simulator/run_simulator.rst b/docs/source/simulator/run_simulator.rst
new file mode 100644
index 0000000..e69de29
--
GitLab