Nicer doc

.hgignore

@@ -55,7 +55,7 @@ image_samples/*/Images.bos*/*.h5
 fluidimage/works/piv/*.h5
 fluidimage/**.dot
 
-doc/generated/*
+doc/_generated/*
 doc/tutorials/*.rst
 doc/tutorials/*.h5
 doc/tutorials/**.png

CHANGES.md

@@ -3,39 +3,39 @@
 See also the
 [unreleased changes](https://foss.heptapod.net/fluiddyn/fluidimage/-/compare/0.1.5...branch%2Fdefault).
 
-# [0.1.5] (2023-02-15)
+## [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
@@ -46,15 +46,15 @@ See also the
 - 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))
 - 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).

doc/CONTRIBUTING.md

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

doc/Makefile

@@ -46,7 +46,7 @@ clean:
 	rm -rf $(BUILDDIR)/*
 
 cleanall: clean
-	rm -rf generated html.zip
+	rm -rf _generated html.zip
 
 cleancache:
 	rm -rf _jupyter_cache

doc/autosum.rst

@@ -0,0 +1,5 @@
+
+.. autosummary::
+   :toctree: _generated/
+
+   fluidimage

doc/build-from-source.md

@@ -0,0 +1,303 @@
+# Build from source
+
+## Requirements
+
+To build Fluidimage from source, ones needs:
+
+- A modern Python (>=3.9) with Python headers and `pip`
+
+- A decent amount of RAM (at least few GB available).
+
+- A C++ compiler fully compliant with the C++-11 standard (currently not Intel
+  compilers)
+
+## Get the source
+
+Fluidimage development uses the revision control software [Mercurial] with modern
+Mercurial extensions like [Evolve] and [Topic]. The main repository is hosted
+[here](https://foss.heptapod.net/fluiddyn/fluidimage) in
+[Heptapod](https://heptapod.net/).
+
+There are other ways to get the source but we are going here to assume that you
+can install [Mercurial]. It can be useful when working with Fluidimage source to
+[fully setup Mercurial with these extensions and learn a bit of Mercurial](http://fluiddyn.readthedocs.org/en/latest/mercurial_heptapod.html).
+Then, the Fluidimage repository can be cloned with
+
+```sh
+
+hg clone https://foss.heptapod.net/fluiddyn/fluidimage
+
+```
+
+```{admonition} Why Mercurial/Heptapod and not simply Git/Github?
+
+We consider that modern Mercurial is really great, even better in some aspects
+than Git. Moreover, we do not think that it is a good thing that the whole
+open-source ecosystem depends on Github, a close-source project owned by
+Microsoft.
+
+Thanks to [Octobus](https://octobus.net/) and [Clever
+Cloud](https://www.clever-cloud.com) for providing <https://foss.heptapod.net>!
+
+```
+
+## Installing from the repository
+
+### Simple installation from source
+
+We recommend to create a clean virtual environment, for example with:
+
+```sh
+cd fluidimage
+python3 -m venv .venv
+. .venv/bin/activate
+pip install pip -U
+```
+
+Then, let us use `pip` to install the local project:
+
+```sh
+pip install . -v
+```
+
+```{note}
+
+`-v` toggles `pip` verbose mode so that we see the compilation log and
+can check that everything goes well.
+
+```
+
+Moreover, the build (which uses [Meson]) can be controlled through environment
+variables (for the C++ compilation) and options. The particular build options for
+Fluidimage are defined in the file `meson.options` which contains:
+
+```{literalinclude} ../meson.options
+```
+
+To choose a value different from the default value, one can use this ugly syntax:
+
+```sh
+pip install . -v --config-settings=setup-args=-Dtransonic-backend=python
+# or
+pip install . -v -C setup-args=-Dtransonic-backend=python
+```
+
+```{admonition} Let's decompose this syntax!
+
+There are 3 levels:
+
+- `--config-settings` / `-C` is a `pip` option to pass configuration to the PEP
+  517 build backend (for Fluidimage [meson-python]).
+
+- `setup-args` is [understood by
+  meson-python](https://meson-python.readthedocs.io/en/latest/reference/config-settings.html)
+
+- `transonic-backend` is a Fluidimage build option. But one needs to add the `-D`
+  for [Meson]!
+
+```
+
+````{important}
+
+One can activate a performance oriented and not portable build using:
+
+```sh
+pip install . -v -C setup-args=-Dnative=true
+```
+
+````
+
+````{note}
+
+Recent versions of `pip` allow one to specify different options like so:
+
+```sh
+pip install . -v \
+  -C setup-args=-Dtransonic-backend=python \
+  -C setup-args=-Duse-xsimd=false
+```
+
+````
+
+Of course, one can also change values of
+[other buildin Meson options](https://meson-python.readthedocs.io/en/latest/reference/config-settings.html).
+
+````{warning}
+(compile-args-j2)=
+
+[Meson] builds Fluidimage binaries in parallel. This speedups the build process a
+lot on most computers. However, it can be a very bad idea on computers with not
+enough memory. One can control the number of processes launched in parallel
+with:
+
+```sh
+pip install . -v -C compile-args=-j2
+```
+
+````
+
+````{Admonition} Another example to set the optimization level
+
+The default optimization level is `-O3`. One can change that with:
+
+```sh
+pip install . -v -C setup-args=-Doptimization=2
+```
+
+````
+
+```{admonition} Advanced compilation configuration
+
+The environment variables `CC`, `CXX`, `CFLAGS`, `CXXFLAGS` and `LDFLAGS`
+are honored.
+
+Note that Fluidimage builds are not sensible to the [`~/.pythranrc` file](pythranrc)!
+
+```
+
+```{admonition} FAQ
+
+- How to know which compilers and compilation flags are used?
+  How to check if XSIMD was indeed used?
+
+  One can study the file `build/cp39/compile_commands.json`.
+
+- How to differentiate a native build from a
+  regular build to produce binaries usable on other computers?
+
+  By default the produced wheels should be portable. There is the `native`
+  build option to target the exact CPU used for compilation.
+
+- How to produce a wheel for other architectures (cross-compilation)?
+
+  ???
+
+```
+
+### Setup a full developer environment with editable installation
+
+Let us first present the tools used for Fluidimage development.
+
+- [PDM] is a modern Python package and dependency manager,
+
+- [Meson] is an open source build system (in particular used by Scipy),
+
+- [Nox] is a command-line tool that automates testing in multiple Python
+  environments,
+
+- [Pytest] is the most popular testing framework for Python,
+
+- [pip] is the official package installer for Python,
+
+- [Pythran] is an ahead of time compiler for a subset of the Python language, with
+  a focus on scientific computing,
+
+- [Transonic] is a pure Python package to accelerate modern Python-Numpy code with
+  different accelerators (in particular Pythran).
+
+Fluidimage is built with [Meson]. We use [PDM] for Fluidimage development. [Pytest]
+and [Nox] are used for testing. We use [Pythran] through [Transonic] to accelerate
+some numerical kernels written in Python.
+
+#### Standard Python from Python.org
+
+We present here how one can build Fluidimage from source like the main developers
+and users.
+
+##### Install PDM
+
+A first step is to install [PDM] as an external independant application. I (Pierre
+Augier) usually use [pipx] for that but
+[there are other methods](https://pdm-project.org/latest/#installation).
+
+```sh
+python3 -m pip install pipx
+pipx install pdm -U
+```
+
+Installing in editable mode is a bit particular with Meson, since editable
+installations are incompatible with isolated builds, meaning that all build
+dependencies have to be installed in the main virtual environment! Fortunatelly,
+it's not too difficult with [PDM]. From the root directory of the repository, just
+run:
+
+```sh
+pdm install --no-self
+```
+
+This command creates a virtual environment and installs all build and runtime
+dependencies. You can then activate this environment and build/install Fluidimage
+with:
+
+```sh
+. .venv/bin/activate
+pip install -e . -v --no-build-isolation --no-deps
+```
+
+### Conda-based Python with conda-forge and Pixi
+
+One can use [Pixi] to setup a developer environment based on [conda-forge] and
+compile from source. From the root directory of Fluidimage repository, just run:
+
+```sh
+pixi run install-editable
+```
+
+Then, `pip` is available and previous commands should work.
+
+## Advice for developers
+
+### Run the tests
+
+You can run some unit tests by running `make tests` (shortcut for
+`fluidsim-test -v`) or `make tests_mpi` (shortcut for
+`mpirun -np 2 fluidsim-test -v`). Alternatively, you can also run `pytest` from
+the root directory or from any of the source directories.
+
+(pythranrc)=
+
+### About using Pythran to compile functions
+
+When developing with Pythran, it can be useful to have a `~/.pythranrc` file, with
+for example something like (see
+[the dedicated section in Pythran documentation](https://pythran.readthedocs.io/en/latest/MANUAL.html#customizing-your-pythranrc)):
+
+```sh
+
+[pythran]
+complex_hook = True
+
+[compiler]
+CXX=clang++
+CC=clang
+
+```
+
+Note however, that Fluidimage build does not take into account this file! Instead
+there is a build option `pythran-complex-hook` and one can use environment
+variables to change the C++ compilation (performed with [Meson]).
+
+### Set the MESONPY_EDITABLE_VERBOSE mode
+
+It can be useful to set this environment variable when using the editable mode.
+
+```sh
+export MESONPY_EDITABLE_VERBOSE=1
+```
+
+See
+https://meson-python.readthedocs.io/en/latest/how-to-guides/editable-installs.html#verbose-mode
+
+[conda-forge]: https://conda-forge.org/
+[evolve]: https://www.mercurial-scm.org/doc/evolution/
+[mercurial]: https://www.mercurial-scm.org/
+[meson]: https://mesonbuild.com
+[nox]: https://nox.thea.codes
+[pdm]: https://pdm-project.org
+[pip]: https://pip.pypa.io
+[pipx]: https://github.com/pypa/pipx
+[pixi]: https://pixi.sh/
+[pytest]: https://docs.pytest.org
+[pythran]: https://pythran.readthedocs.io
+[topic]: https://www.mercurial-scm.org/doc/evolution/tutorials/topic-tutorial.html
+[transonic]: https://transonic.readthedocs.io