Merge pull request #121 from Ouranosinc/documentation-cleanup

Documentation cleanup

.pre-commit-config.yaml

@@ -51,6 +51,22 @@ repos:
     hooks:
       - id: blackdoc
         additional_dependencies: [ 'black==23.9.1' ]
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.6.1
+    hooks:
+      - id: nbstripout
+        files: '.ipynb'
+        args: [ '--extra-keys', 'metadata.kernelspec' ]
+  - repo: https://github.com/pycqa/pydocstyle
+    rev: 6.3.0
+    hooks:
+      - id: pydocstyle
+        args: [ '--config=setup.cfg' ]
+  - repo: https://github.com/keewis/blackdoc
+    rev: v0.3.8
+    hooks:
+      - id: blackdoc
+        additional_dependencies: [ 'black==23.9.1' ]
   - repo: https://github.com/adrienverge/yamllint.git
     rev: v1.32.0
     hooks:

.readthedocs.yml

@@ -16,7 +16,7 @@ formats:
 build:
   os: ubuntu-22.04
   tools:
-    python: "mambaforge-4.10"
+    python: "mambaforge-22.9"
   jobs:
     pre_build:
       - sphinx-apidoc -o docs/apidoc --module-first figanos

HISTORY.rst

@@ -23,6 +23,11 @@ Internal changes
 * Clean up of the dependencies to remove the notebooks deps from the core deps.
 * `figanos` now uses Trusted Publishing to publish the package on PyPI and TestPyPI. (:pull:`113`).
 * The official Ouranos logos have been removed from the repository. They can now be installed if required via the ``figanos.Logos.install_ouranos_logos`` class method. (:issue:`115`, :pull:`119`).
+* Documentation adjustments. (:pull:`121`):
+    * Added a few `pre-commit` hooks for cleaning up notebooks and ensuring that docstrings are properly formatted.
+    * Cleaned up the docstrings of a few functions, added some module-level strings, minor typo fixes.
+    * Set `nbsphinx` in the documentation to always run (with th exception of one complex cell).
+    * The `environment.yml` Python version is set to 3.11 to reduce the dependency solver complexity.
 
 0.2.0 (2023-06-19)
 ------------------

MANIFEST.in

@@ -9,7 +9,7 @@ include requirements_docs.txt
 
 recursive-include figanos *.json *.mplstyle *.py *.txt
 recursive-include docs *.rst conf.py Makefile make.bat *.jpg *.png *.gif
-recursive-include figanos/data *.json *.txt *.yml
+recursive-include figanos/data *.json *.png *.txt *.yml
 
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]

docs/conf.py

@@ -47,6 +47,8 @@
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth = 2
 
+nbsphinx_execute = "always"
+
 # To ensure that underlined fields (e.g. `_field`) are shown in the docs.
 autodoc_default_options = {
     "members": True,