Fix docs build and reduce warnings

.github/workflows/quality-checks.yaml

@@ -56,3 +56,19 @@ jobs:
         python-version: 3.7
     - run: pip install tox
     - run: tox -e notebooks
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.7
+    - run: pip install tox
+    - run: |
+        TEMP_DEB="$(mktemp)" &&
+        wget -O "$TEMP_DEB" 'https://github.com/jgm/pandoc/releases/download/2.10.1/pandoc-2.10.1-1-amd64.deb' &&
+        sudo dpkg -i "$TEMP_DEB"
+        rm -f "$TEMP_DEB"
+    - run: tox -e docs
+

common_build/format/constraints.txt

@@ -1,8 +1,8 @@
 appdirs==1.4.4
 black==20.8b1
 click==7.1.2
-flake8==3.9.0
-importlib-metadata==3.10.1
+flake8==3.9.1
+importlib-metadata==4.0.1
 isort==5.8.0
 mccabe==0.6.1
 mypy-extensions==0.4.3

common_build/taskipy/constraints.txt

@@ -5,8 +5,8 @@ black==20.8b1
 click==7.1.2
 coverage==5.5
 filelock==3.0.12
-flake8==3.9.0
-importlib-metadata==3.10.1
+flake8==3.9.1
+importlib-metadata==4.0.1
 iniconfig==1.1.1
 isort==5.8.0
 lazy-object-proxy==1.6.0

docs/Makefile

@@ -31,4 +31,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -W $(SPHINXOPTS) $(O)

docs/README.md

@@ -1,15 +1,13 @@
 # Building documentation
 
-Install dependencies for building documentation by first installing dependencies for the notebooks
-(see the [root README.md](../README.md#installation) for instructions). Then run 
-```
-$ pip install -r requirements.txt -c constraints.txt
-```
-Build the documentation with
+To build the documentation, ensure you have both [tox](https://tox.readthedocs.io) and [pandoc](https://github.com/jgm/pandoc/releases/) installed.
+Then run the following from the repository root directory:
+
 ```
-$ make html
+$ tox -e docs
 ```
-Open `_build/html/index.html` in a browser to view the docs.
+
+Open `docs/_build/html/index.html` in a browser to view the docs.
 
 # License
 

docs/conf.py

@@ -58,6 +58,7 @@
 extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.doctest",
 ]
 add_module_names = False
 autosectionlabel_prefix_document = True

docs/constraints.txt

@@ -14,7 +14,7 @@ docutils==0.16
 entrypoints==0.3
 idna==2.10
 imagesize==1.2.0
-importlib-metadata==3.10.1
+importlib-metadata==4.0.1
 ipython==7.22.0
 ipython-genutils==0.2.0
 jedi==0.18.0
@@ -41,7 +41,7 @@ prompt-toolkit==3.0.18
 ptyprocess==0.7.0
 pybtex==0.24.0
 pybtex-docutils==1.0.0
-pydata-sphinx-theme==0.6.0
+pydata-sphinx-theme==0.6.1
 Pygments==2.8.1
 pyparsing==2.4.7
 pyrsistent==0.17.3

docs/make.bat

@@ -43,7 +43,7 @@ if errorlevel 9009 (
 goto end
 
 :help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% -W %SPHINXOPTS% %O%
 
 :end
 popd

docs/notebooks/constraints.txt

@@ -16,19 +16,20 @@ cycler==0.10.0
 dataclasses==0.6
 decorator==5.0.7
 defusedxml==0.7.1
+Deprecated==1.2.12
 deprecation==2.1.0
 dm-tree==0.1.6
 entrypoints==0.3
 flatbuffers==1.12
 gast==0.3.3
-google-auth==1.28.1
+google-auth==1.29.0
 google-auth-oauthlib==0.4.4
 google-pasta==0.2.0
-gpflow==2.1.4
+gpflow==2.1.5
 grpcio==1.32.0
 h5py==2.10.0
 idna==2.10
-importlib-metadata==3.10.1
+importlib-metadata==4.0.1
 ipykernel==5.5.3
 ipython==7.22.0
 ipython-genutils==0.2.0
@@ -38,8 +39,8 @@ json5==0.9.5
 jsonschema==3.2.0
 jupyter-client==6.2.0
 jupyter-core==4.7.1
-jupyter-packaging==0.9.1
-jupyter-server==1.6.1
+jupyter-packaging==0.9.2
+jupyter-server==1.6.4
 jupyterlab==3.0.14
 jupyterlab-pygments==0.1.2
 jupyterlab-server==2.4.0
@@ -93,11 +94,12 @@ Send2Trash==1.5.0
 six==1.15.0
 sniffio==1.2.0
 tabulate==0.8.9
-tensorboard==2.4.1
+tensorboard==2.5.0
+tensorboard-data-server==0.6.0
 tensorboard-plugin-wit==1.8.0
 tensorflow==2.4.1
 tensorflow-estimator==2.4.0
-tensorflow-probability==0.12.1
+tensorflow-probability==0.12.2
 termcolor==1.1.0
 terminado==0.9.4
 testpath==0.4.4

docs/refs.bib

@@ -102,3 +102,14 @@ @inproceedings{Gonzalez:2016
     booktitle={Artificial intelligence and statistics},
     year={2016}
 }
+
+@article{gramacy2012cases,
+  title={Cases for the nugget in modeling computer experiments},
+  author={Gramacy, Robert B and Lee, Herbert KH},
+  journal={Statistics and Computing},
+  volume={22},
+  number={3},
+  pages={713--722},
+  year={2012},
+  publisher={Springer}
+}

docs/tutorials.rst

@@ -38,6 +38,12 @@ The following tutorials (or sections thereof) explain how to use and extend spec
 * :ref:`How do I customize the model optimization routine?<notebooks/failure_ego:Create a custom optimize method>`
 * :doc:`How do I recover a failed optimization loop?<notebooks/recovering_from_errors>`
 
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   notebooks/recovering_from_errors
+
 Run the tutorials interactively
 -------------------------------
 

tests/constraints.txt

@@ -7,17 +7,18 @@ chardet==4.0.0
 cloudpickle==1.6.0
 dataclasses==0.6
 decorator==5.0.7
+Deprecated==1.2.12
 dm-tree==0.1.6
 flatbuffers==1.12
 gast==0.3.3
-google-auth==1.28.1
+google-auth==1.29.0
 google-auth-oauthlib==0.4.4
 google-pasta==0.2.0
-gpflow==2.1.4
+gpflow==2.1.5
 grpcio==1.32.0
 h5py==2.10.0
 idna==2.10
-importlib-metadata==3.10.1
+importlib-metadata==4.0.1
 iniconfig==1.1.1
 Keras-Preprocessing==1.1.2
 Markdown==3.3.4
@@ -39,11 +40,12 @@ rsa==4.7.2
 scipy==1.6.2
 six==1.15.0
 tabulate==0.8.9
-tensorboard==2.4.1
+tensorboard==2.5.0
+tensorboard-data-server==0.6.0
 tensorboard-plugin-wit==1.8.0
 tensorflow==2.4.1
 tensorflow-estimator==2.4.0
-tensorflow-probability==0.12.1
+tensorflow-probability==0.12.2
 termcolor==1.1.0
 toml==0.10.2
 typing-extensions==3.7.4.3

tox.ini

@@ -37,3 +37,5 @@ commands =
     tests: pytest
     notebooks: pip install . -r notebooks/requirements.txt -c notebooks/constraints.txt
     notebooks: bash -c "res=0; for f in notebooks/*.py; do python "$f" || res=$?; done; $(exit $res)"
+    docs: pip install . -r notebooks/requirements.txt -c notebooks/constraints.txt -r docs/requirements.txt -c docs/constraints.txt
+    docs: bash -c "cd docs; make html; make html"

trieste/acquisition/function.py

@@ -524,20 +524,21 @@ def expected_hv_improvement(
     For easier calculation, this sub-calculation can be reformulated as a combination
     of two generalized expected improvements, corresponding to Psi (Eq. 44) and Nu (Eq. 45)
     function calculations, respectively.
+
     Note:
     1. Since in Trieste we do not assume the use of a certain non-dominated region partition
-        algorithm, we do not assume the last dimension of the partitioned cell has only one
-        (lower) bound (i.e., minus infinity, which is used in the :cite:`yang2019efficient` paper).
-        This is not as efficient as the original paper, but is applicable to different non-dominated
-        partition algorithm.
+    algorithm, we do not assume the last dimension of the partitioned cell has only one
+    (lower) bound (i.e., minus infinity, which is used in the :cite:`yang2019efficient` paper).
+    This is not as efficient as the original paper, but is applicable to different non-dominated
+    partition algorithm.
     2. As the Psi and nu function in the original paper are defined for maximization problems,
-        we inverse our minimisation problem (to also be a maximisation), allowing use of the
-        original notation and equations.
+    we inverse our minimisation problem (to also be a maximisation), allowing use of the
+    original notation and equations.
 
     :param model: The model of the objective function.
     :param pareto: Pareto class
-    :param reference_point The reference point for calculating hypervolume
-    :return The expected_hv_improvement acquisition function modified for objective
+    :param reference_point: The reference point for calculating hypervolume
+    :return: The expected_hv_improvement acquisition function modified for objective
         minimisation. This function will raise :exc:`ValueError` or
         :exc:`~tf.errors.InvalidArgumentError` if used with a batch size greater than one.
     """

trieste/acquisition/sampler.py

@@ -68,6 +68,7 @@ def sample(self, at: TensorType) -> TensorType:
         """
         Return approximate samples from of the objective function's minimser. We return only
         unique samples.
+
         :param at: Where to sample the predictive distribution, with shape `[N, D]`, for points
             of dimension `D`.
         :return: The samples, of shape `[S, D]`, where `S` is the `sample_size`.
@@ -100,6 +101,7 @@ class GumbelSampler(Sampler):
     def sample(self, at: TensorType) -> TensorType:
         """
         Return approximate samples from of the objective function's minimum value.
+
         :param at: Points at where to fit the Gumbel distribution, with shape `[N, D]`, for points
             of dimension `D`. We recommend scaling `N` with search space dimension.
         :return: The samples, of shape `[S, 1]`, where `S` is the `sample_size`.

trieste/data.py

@@ -36,7 +36,7 @@ class Dataset:
 
     def __post_init__(self) -> None:
         """
-        :raise ValueError (or InvalidArgumentError): If ``query_points`` or ``observations`` have
+        :raise ValueError (or InvalidArgumentError): If ``query_points`` or ``observations`` have \
             rank less than two, or they have unequal shape in any but their last dimension.
         """
         tf.debugging.assert_rank_at_least(self.query_points, 2)

trieste/utils/objectives.py

@@ -69,7 +69,7 @@ def branin(x: TensorType) -> TensorType:
 def gramacy_lee(x: TensorType) -> TensorType:
     """
     The Gramacy & Lee function, typically evaluated over :math:`[0.5, 2.5]`. See
-    :cite:`gramacy2010cases` and :cite:`Ranjan2013` for details.
+    :cite:`gramacy2012cases` for details.
 
     :param x: Where to evaluate the function, with shape [..., 1].
     :return: The function values, with shape [..., 1].

trieste/utils/pareto.py

@@ -327,6 +327,7 @@ def hypercell_bounds(
     ) -> tuple[TensorType, TensorType]:
         """
         Get the partitioned hypercell's lower and upper bounds.
+
         :param anti_reference: a worst point to use with shape [D].
             Defines the lower bound of the hypercell
         :param reference: a reference point to use, with shape [D].