Doc and tests

.gitlab-ci.yml

@@ -84,12 +84,7 @@ pages:
   variables:
     FLUIDFFT_TRANSONIC_BACKEND: "python"
   script:
-    - python -m venv .venv
-    - . .venv/bin/activate
-    - pip install fluidfft --no-deps
-    - pdm sync -G doc -G fft -G test --no-self
-    - pip install . --config-settings=setup-args=-Dtransonic-backend=python --no-deps
-    - pdm run xvfb-run --auto-servernum sphinx-build -W -b html -d doc/_build/doctrees doc doc/_build/html
+    - xvfb-run --auto-servernum nox -s doc
     - mkdir -p public/$CI_COMMIT_REF_NAME
     - rsync -rvc --delete doc/_build/html/* public/$CI_COMMIT_REF_NAME/
     # This directory can become too large leading to error.

.hgignore

@@ -63,7 +63,8 @@ doc/ipynb/*.nbconvert.ipynb
 doc/ipynb/**.png
 doc/examples/oar_launcher*
 doc/examples/topo.dot
-*/.ipynb_checkpoints/*
+**/.ipynb_checkpoints/*
+doc/_jupyter_cache
 
 fluidimage/post_proc/*.h5
 

AUTHORS.rst → AUTHORS.md

@@ -1,3 +1,4 @@
+# Main contributors
 
 The main contributors are:
 

CHANGES.rst → CHANGES.md

@@ -1,44 +1,41 @@
+# Release notes
 
-0.1.5_ (2023-02-15)
--------------------
+See also the
+[unreleased changes](https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.5...branch%2Fdefault).
+
+# [0.1.5] (2023-02-15)
 
 - Requires Python 3.9
 - Improves legend, warnings, error log and documentation
 
-0.1.4_ (2022-12-13)
--------------------
+# [0.1.4] (2022-12-13)
 
 - Support Python 3.10
 - Avoid a bug with pyfftw 0.13
 
-0.1.3_ (2021-09-29)
--------------------
+# [0.1.3] (2021-09-29)
 
 - Many bugfixes!
 - Improve VectorFieldOnGrid and ArrayOfVectorFieldsOnGrid
 - UVmat compatibility
 - Fix incompatibility OpenCV and PyQt5
 
-0.1.2_ (2019-06-05)
--------------------
+# [0.1.2] (2019-06-05)
 
 - Bugfix install Windows
 
-0.1.1_ (2019-05-23)
--------------------
+# [0.1.1] (2019-05-23)
 
 - Optical flow computation
 - Bugfixes + internal code improvements
 
-0.1.0 (2018-10-03)
-------------------
+# 0.1.0 (2018-10-03)
 
 - New topologies and executors with Trio!
 - Much better coverage & many bugfixes!
 - Better surface tracking
 
-0.0.3 (2018-08-29)
-------------------
+# 0.0.3 (2018-08-29)
 
 - Requirement Python >= 3.6
 - Surface tracking
@@ -49,22 +46,21 @@
 - fluidimslideshow-pg and fluidimviewer-pg (based on PyQtgraph)
 - OpenCV backend for preprocessing
 
-0.0.2 (2017-04-13)
-------------------
+# 0.0.2 (2017-04-13)
 
 - Bug fixes and documentation changes.
 - Continuous integration (python 2.7 and 3.5) with bitbucket pipelines
-  (`coverage ~40% <https://codecov.io/gh/fluiddyn/fluidimage>`_)
+  ([coverage ~40%](https://codecov.io/gh/fluiddyn/fluidimage))
 - Preprocessing of images.
 - First simple GUI (`fluidimviewer` and `fluidimlauncher`).
 
-0.0.1b (2016-05-31)
--------------------
+# 0.0.1b (2016-05-31)
 
 - Topology and waiting queues classes to run work in parallel.
 - PIV work and topology (multipass, different correlation methods).
 
-.. _0.1.3: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.3...0.1.4
-.. _0.1.3: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.2...0.1.3
-.. _0.1.2: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.1...0.1.2
-.. _0.1.1: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.0...0.1.1
+[0.1.1]: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.0...0.1.1
+[0.1.2]: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.1...0.1.2
+[0.1.3]: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.2...0.1.3
+[0.1.4]: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.3...0.1.4
+[0.1.5]: https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.4...0.1.5

doc/Makefile

@@ -48,20 +48,12 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
-cleanipynb:
-	rm -rf $(IPYTHON_NOTEBOOKS_DIR)
-	rm -f $(IPYTHON_NOTEBOOKS_RST)
-	rm -f ipynb/*.nbconvert.ipynb
-
-clean: cleanipynb
+clean:
 	rm -rf $(BUILDDIR)/*
 
 cleanall: clean
 	rm -rf generated html.zip
 
-cleannbconvert.ipynb:
-	rm -f ipynb/*.nbconvert.ipynb
-
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

doc/authors.md

@@ -0,0 +1 @@
+../AUTHORS.md

doc/changes.md

@@ -0,0 +1 @@
+../CHANGES.md

doc/conf.py

@@ -11,27 +11,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
 
 os.environ["OMP_NUM_THREADS"] = "1"
 
-# to be able to build the doc without h5py with Read the docs
-
-import fluiddoc
-
-if fluiddoc.on_rtd:
-    print("Mock modules to build the documentation on READTHEDOCS.")
-    # this package comes from fluiddyn
-    fluiddoc.mock_modules(
-        [
-            "theano",
-            "reikna.cluda",
-            "reikna.fft",
-            "reikna.transformations",
-        ]
-    )
-
 import fluidimage
 
 # we want this module to be importable.
@@ -42,16 +25,6 @@
 
     traceback.print_exc()
 
-from fluiddoc.ipynb_maker import ipynb_to_rst
-
-ipynb_to_rst()
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# 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.
-sys.path.insert(0, os.path.abspath("../scripts"))
-sys.path.insert(0, os.path.abspath("./"))
-
 # -- General configuration ----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -70,21 +43,27 @@
     "sphinx.ext.autosummary",
     "numpydoc",
     "fluiddoc.mathmacro",
+    "sphinx.ext.inheritance_diagram",  # requires Graphviz
+    "myst_nb",
+    "sphinx_copybutton",
 ]
 
-try:
-    import readthedocs_ext
-except ImportError:
-    pass
-else:
-    extensions.append("readthedocs_ext.readthedocs")
-
+# Execute ipynb files into with a cache ...
+nb_execution_mode = "cache"
+nb_execution_cache_path = "./_jupyter_cache"
+os.makedirs(nb_execution_cache_path, exist_ok=True)
+# ... except these ipynb files
+nb_execution_excludepatterns = ["ipynbslides/*"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+    ".myst": "myst-nb",
+}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -149,7 +128,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 # html_theme = 'default'
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
 
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -312,3 +291,25 @@
 autodoc_member_order = "bysource"
 
 todo_include_todos = True
+
+nb_execution_raise_on_error = True
+nb_execution_show_tb = True
+nb_merge_streams = True
+nb_execution_timeout = 120
+
+myst_enable_extensions = [
+    "amsmath",
+    # "attrs_inline",
+    "colon_fence",
+    # "deflist",
+    "dollarmath",
+    # "fieldlist",
+    # "linkify",
+    # "replacements",
+    # "smartquotes",
+    # "strikethrough",
+    "substitution",
+    # "tasklist",
+]
+
+suppress_warnings = ["mystnb.unknown_mime_type"]

doc/index.rst

@@ -1,7 +1,5 @@
 .. FluidImage documentation master file
 
-.. include:: ../README.rst
-
 User Guide
 ----------
 

doc/ipynb/tuto_calibration2dsimple.ipynb

@@ -59,7 +59,7 @@
    "outputs": [],
    "source": [
     "with h5py.File(path_piv) as file:\n",
-    "    shape_im = file['couple/shape_images'].value\n",
+    "    shape_im = file['couple/shape_images'][...]\n",
     "\n",
     "point0 = (10, 20)\n",
     "point1 = (10, 10)\n",
@@ -310,4 +310,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}