Improve doc (and fix readthedocs build?)

snek5000 · Dec 1, 2022 · 47f66cb · 47f66cb
1 parent d0742fe
commit 47f66cb
Show file tree

Hide file tree

Showing 6 changed files with 53 additions and 33 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,8 +6,11 @@ Something does not work and you wish to fix it? Are you curious to see how it wo
 development:
 
 ```sh
-# Clone
-git clone --recursive https://github.com/snek5000/snek5000.git
+# First install Nek5000
+git clone https://github.com/snek5000/Nek5000.git
+export NEK_SOURCE_ROOT=$PWD/Nek5000
+
+git clone https://github.com/snek5000/snek5000.git
 
 # Activate paths: Start here. Always!
 cd snek5000
@@ -18,14 +21,17 @@ Now you should setup a Python environment. There are two ways to do this (and it
 be done only once):
 
 - Using `venv`
+
   ```sh
   python -m venv venv
   source venv/bin/activate
   ```
+
 - Using `conda`
+
   ```sh
-  conda env create -n snek5000
-  conda activate snek5000
+  conda env create -n env-snek5000
+  conda activate env-snek5000
   ```
 
 Finally, to install in development mode:
@@ -47,21 +53,14 @@ nox -s pip-sync
   ```
 
 - **Branching model**: The development uses branches and pull-requests for experimental
-  features. We also rely on [git submodules](https://www.git-scm.com/docs/git-submodule)
-  to track `Nek5000`. You may find the following git branches when you clone `snek5000`:
+  features. You may find the following git branches when you clone `snek5000`:
 
   - `master`: main branch
   - `fix/...`, `enh/...`: feature branches
 
   Executing the following command would configure git to work with submodules easily and
   ensures consistency:
 
-  ```sh
-  # Enable recursion for relevant commands, such that
-  # regular commands recurse into submodules by default
-  git config submodule.recurse true
-  ```
-
 - **Testing**: [Run `pytest`](https://pytest.readthedocs.io/) from the top-level
   directory. The test-cases can be found under `tests/` directory. To run the slow tests
   too execute `pytest --runslow`.

diff --git a/docs/how-to/edit_tutorials.md → docs/dev/edit_tutorials.md b/docs/how-to/edit_tutorials.md → docs/dev/edit_tutorials.md
diff --git a/docs/dev/index.rst b/docs/dev/index.rst
@@ -5,9 +5,9 @@ Developer Guide
 
 To install for development, execute::
 
-   git clone --recursive https://github.com/snek5000/snek5000.git
+   git clone https://github.com/snek5000/snek5000.git
    cd snek5000
-   pip install -e ."[dev]"
+   pip install -e ".[dev]"
 
 .. note::
 
@@ -29,3 +29,9 @@ To install for development, execute::
    nek
    roadmap
    release
+
+.. toctree::
+   :maxdepth: 1
+   :caption: How to for developers / maintainers of Snek5000 package
+
+   edit_tutorials.md
diff --git a/docs/dev/release.md b/docs/dev/release.md
@@ -18,44 +18,44 @@ For demonstration's sake, we assume that the next version is `$VERSION`.
 
 - Install nox:
 
-  ```
+  ```bash
   pip install nox
   ```
 
 - Ensure tests pass locally and on CI:
 
-  ```
+  ```bash
   nox -s tests
   ```
 
 - Compile documentation:
 
-  ```
+  ```bash
   nox -s docs
   ```
 
 - Commit changes and make an annotated tag:
 
-  ```
+  ```bash
   git commit
   git tag -a $VERSION
   ```
 
 - Build and upload to [TestPyPI]:
 
-  ```
+  ```bash
   nox -s testpypi
   ```
 
 - Download, test and upload to [PyPI]:
 
-  ```
+  ```bash
   nox -s pypi
   ```
 
 - Upload to repository:
 
-  ```
+  ```bash
   git push --follow-tags --atomic origin main
   ```
 

diff --git a/docs/how-to/index.md b/docs/how-to/index.md
@@ -17,12 +17,3 @@ history_points.md
 maxdepth: 1
 ---
 ```
-
-## For developer / maintainer of Snek5000 package
-
-```{toctree}
----
-maxdepth: 1
----
-edit_tutorials.md
-```
diff --git a/docs/tuto_phill.md b/docs/tuto_phill.md
@@ -45,18 +45,23 @@ params.nek.stat.io_step = 10
 sim = Simul(params)
 ```
 
+We recall that this instanciation of the class `Simul` creates the simulation directory
+on the disk with the following files:
+
 ```{code-cell} ipython3
 !ls {sim.path_run}
 ```
 
 ## Execute the simulation
 
+### Snakemake rules
+
 To run the simulation we need to execute certain commands. These are described using
 [snakemake](https://snakemake.rtfd.io) in the Snakefile. Let's look at the rules defined
 in the Snakefile (which are nearly generic for any Nek5000 case).
 
 ```{code-cell} ipython3
-sim.make.list()
+sim.make.list();
 ```
 
 The rules in the Snakefile are either shell commands or Python code which handle
@@ -73,15 +78,28 @@ From a user's perspective the following rules are essential:
 - `run_fg`: Run the simulation in the foreground (blocking, till the simulation is over
   / terminated)
 
+```{note}
+
+In real life, simulations are usually submitted with Snek5000 from a script and
+we are going to call Snakemake from the Snek5000 Python API with a call similar
+to `sim.make.exec("run_fg", nproc=2)` (as in the following example).
+
+However, there is also a command `snek-make` that can be run from the
+simulation directory to list and invoke the Snakemake rules. See `snek-make -h`
+and `snek-make -l`.
+
+```
+
 <!-- #region tags=[] -->
 
 ### Debug mode
 
-During development, it is useful to turn on the debug environment variable.
+During development, it can be useful to turn on the debug environment variable which can
+be done in Python with:
 
 <!-- #endregion -->
 
-```{code-cell} ipython3
+```python
 import os
 os.environ["SNEK_DEBUG"] = "1"
 ```
@@ -94,6 +112,8 @@ doing so, snek5000 would:
 - activate the code blocks under the preprocessing flag in Fortran sources
   `#ifdef DEBUG`
 
+### Execution of the main script
+
 Now let's execute the simulation. We will use the script
 [docs/examples/scripts/tuto_phill.py](https://github.com/snek5000/snek5000/tree/main/docs/examples/scripts/tuto_phill.py),
 which contains:
@@ -119,6 +139,8 @@ process = run(
 print(f"Script executed in {perf_counter() - t_start:.2f} s")
 ```
 
+### Snek5000 and Nek5000 log
+
 The simulation is done! Let's look at its output:
 
 ```{code-cell} ipython3
@@ -143,6 +165,8 @@ if path_run is None:
 path_run
 ```
 
+### Other files produced during the simulation
+
 Let's look at the files in the directory of the simulation
 
 ```{code-cell} ipython3