Merge pull request #287 from CSHS-CWRA/fix_docs

Documentation and docstring adjustments, fix failing notebooks
CSHS-CWRA · Jun 1, 2023 · c17976e · c17976e
2 parents 4162afa + 5aba957
commit c17976e
Show file tree

Hide file tree

Showing 33 changed files with 5,072 additions and 981 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -10,20 +10,21 @@ sphinx:
   configuration: docs/conf.py
   # fail_on_warning might generate hard to fix error, in this case it can be
   # disabled but this also means those errors will fail silently, choose wisely.
-  fail_on_warning: false
+  fail_on_warning: true
 
 build:
   os: ubuntu-22.04
   tools:
     python: "mambaforge-4.10"
   jobs:
     post_install:
-      - pip install .[docs,gis]
+      - pip install .[docs]
     pre_build:
-      - sphinx-apidoc -o docs/apidoc --private --module-first ravenpy
+      - env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/apidoc --private --module-first ravenpy
       - sphinx-build -b linkcheck docs/ _build/linkcheck || true
 
-formats: all
+formats:
+  - pdf
 
 conda:
   environment: environment-rtd.yml

diff --git a/Makefile b/Makefile
@@ -73,10 +73,13 @@ coverage: ## check code coverage quickly with the default Python
 autodoc: clean-docs ## create sphinx-apidoc files:
 	sphinx-apidoc -o docs/apidoc --private --module-first ravenpy
 
+autodoc-custom-index: clean-docs ## create sphinx-apidoc files but with special index handling for indices and indicators
+	env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/apidoc --private --module-first ravenpy
+
 linkcheck: autodoc ## run checks over all external links found throughout the documentation
 	$(MAKE) -C docs linkcheck
 
-docs: linkcheck ## generate Sphinx HTML documentation, including API docs
+docs: autodoc-custom-index ## generate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs html
 ifndef READTHEDOCS
 	$(BROWSER) docs/_build/html/index.html

diff --git a/docs/conf.py b/docs/conf.py
@@ -41,12 +41,12 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "IPython.sphinxext.ipython_console_highlighting",
-    #"nbsphinx",
+    # "nbsphinx",
     "myst_nb",
     "sphinx_click",
     "sphinx_codeautolink",
     "sphinx_copybutton",
-    #"sphinxcontrib.autodoc_pydantic",
+    # "sphinxcontrib.autodoc_pydantic",
 ]
 
 linkcheck_ignore = [
@@ -64,7 +64,8 @@
 autosummary_generate = True
 
 nb_execution_mode = "cache"
-nb_execution_allow_errors = True
+nb_execution_allow_errors = False
+nb_execution_excludepatterns = ["notebooks/*.ipynb", "notebooks/paper/*.ipynb"]
 
 # nbsphinx_execute = "auto"
 # nbsphinx_timeout = 1
@@ -145,7 +146,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".jupyter_cache", "jupyter_execute"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".jupyter_cache", "jupyter_execute", "notebooks/paper"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -154,7 +155,10 @@
 todo_include_todos = False
 
 # Suppress "WARNING: unknown mimetype for ..." when building EPUB.
-suppress_warnings = ["epub.unknown_project_files"]
+suppress_warnings = [
+    "epub.unknown_project_files",
+    "mystnb.unknown_mime_type"
+]
 
 # -- Options for HTML output -------------------------------------------
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -94,6 +94,8 @@ Config(
 Of course, setting an option with an invalid value will raise a `ValidationError`. For example, the error message below suggests there is a typo in the routing method, it should read `ROUTE_DIFFUSIVE_WAVE`:
 
 ```{code-cell} ipython3
+:tags: ["raises-exception"]
+
 Config(Routing="ROUTE_DIFFUSIVE")
 ```
 

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -33,12 +33,14 @@ Python Installation (pip)
 -------------------------
 
 .. warning::
+
    In order to compile the Raven model (provided by the `raven-hydro` package, a C++ compiler (`GCC`, `Clang`, `MSVC`, etc.) and either `GNU Make` (Linux/macOS) or `Ninja` (Windows) must be exposed on the `$PATH`.
 
 .. warning::
+
    The Raven model also requires that NetCDF4 libraries are installed on the system, exposed on the `$PATH`, and discoverable using the `FindNetCDF.cmake` helper script bundled with `raven-hydro`.
 
-   On Linux, this can be provided by the `libnetcdf-dev` system library; On macOS by the `netcdf` homebrew package; And on Windows by using UNIDATA's [pre-built binaries](https://docs.unidata.ucar.edu/netcdf-c/current/winbin.html).
+   On Linux, this can be provided by the `libnetcdf-dev` system library; On macOS by the `netcdf` homebrew package; And on Windows by using UNIDATA's `pre-built binaries <https://docs.unidata.ucar.edu/netcdf-c/current/winbin.html>`_.
 
 In order to perform this from Ubuntu/Debian:
 

diff --git a/docs/notebooks/02_Extract_geographical_watershed_properties.ipynb b/docs/notebooks/02_Extract_geographical_watershed_properties.ipynb