Merge pull request #236 from snek5000/doc-after-0.8.0

Small modifications in the doc after 0.8.0

CONTRIBUTING.md

@@ -46,28 +46,25 @@ nox -s pip-sync
 - **Editor**: Use an editor which supports [EditorConfig](http://editorconfig.org/)
 
 - **Style guide**: For Python code, `black`, `isort` and `flake8` are used to check and
-  lint. Installing `pre-commit` would enforce the style automatically as a git hook.
+  lint. Installing `pre-commit` would enforce the style automatically as a Git hook.
 
   ```sh
   pre-commit install
   ```
 
 - **Branching model**: The development uses branches and pull-requests for experimental
-  features. 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
+  - `main`: main branch
   - `fix/...`, `enh/...`: feature branches
 
-  Executing the following command would configure git to work with submodules easily and
-  ensures consistency:
-
 - **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`.
 
 - **Debugging**: Set the environment variable:
 
-  ```bash
+  ```sh
   export SNEK_DEBUG=true
   ```
 

README.md

@@ -44,7 +44,6 @@ Install it as follows:
 
 ```sh
 export NEK_SOURCE_ROOT="/path/to/Nek5000"
-export PATH="$PATH:$NEK_SOURCE_ROOT/bin"
 
 pip install snek5000
 ```

docs/autosum.rst

@@ -0,0 +1,4 @@
+.. autosummary::
+   :toctree: _generated/
+
+   snek5000

docs/dev/edit_tutorials.md

@@ -1,7 +1,7 @@
 # How to work on tutorials
 
-The tutorials are saved and version controlled as `.myst.md` files (md:myst format) in the
-`docs` directory. They can be opened as standard text file with your favorite text
+The tutorials are saved and version controlled as `.myst.md` files (md:myst format) in
+the `docs` directory. They can be opened as standard text file with your favorite text
 editor. Moreover, these files can be opened as notebooks in Jupyter Lab. One needs to
 start Jupyter Lab from the `docs` directory. When [Jupytext] is installed, you should be
 able to click right on the icon corresponding to the file and to choose "Open with ->

docs/dev/release.md

@@ -18,44 +18,44 @@ For demonstration's sake, we assume that the next version is `$VERSION`.
 
 - Install nox:
 
-  ```bash
+  ```sh
   pip install nox
   ```
 
 - Ensure tests pass locally and on CI:
 
-  ```bash
+  ```sh
   nox -s tests
   ```
 
 - Compile documentation:
 
-  ```bash
+  ```sh
   nox -s docs
   ```
 
 - Commit changes and make an annotated tag:
 
-  ```bash
+  ```sh
   git commit
   git tag -a $VERSION
   ```
 
 - Build and upload to [TestPyPI]:
 
-  ```bash
+  ```sh
   nox -s testpypi
   ```
 
 - Download, test and upload to [PyPI]:
 
-  ```bash
+  ```sh
   nox -s pypi
   ```
 
 - Upload to repository:
 
-  ```bash
+  ```sh
   git push --follow-tags --atomic origin main
   ```
 

docs/examples/snek5000-tgv/README.md

@@ -1,11 +1,11 @@
 # Snek5000 solver for DNS of Taylor-Green Vortices (TGV)
 
-This [Snek5000] solver demonstrate how to write a solver for a particular usecase taken
+This [Snek5000] solver demonstrates how to write a solver for a particular usecase taken
 from the [NekExamples repo]. Something completely different than a high speed train...
 
 ## Install
 
-```bash
+```sh
 pip install snek5000-tgv
 ```
 

docs/how-to/archive-simulation-data.md

@@ -1,24 +1,24 @@
 # How to make a compressed archive of simulation data
 
-Nek5000 simulations can generate a lot of data files. To reduce the strain in your HPC facility, it is often recommended:
+Nek5000 simulations can generate a lot of data files. To reduce the strain in your HPC
+facility, it is often recommended:
 
 1. To limit the **number of files**
 1. Reduce the **disk usage**
 
-We can achieve both without erasing any data by using Snek5000 and efficient
-compression tools namely [`zstandard`](https://en.wikipedia.org/wiki/Zstd) and
-preferably
+We can achieve both without erasing any data by using Snek5000 and efficient compression
+tools namely [`zstandard`](https://en.wikipedia.org/wiki/Zstd) and preferably
 [`bsdtar`](https://www.freebsd.org/cgi/man.cgi?query=bsdtar&sektion=1&format=html)
-(usually faster) if not [GNU `tar`](https://www.gnu.org/software/tar/). If
-unavailable some of these can be installed using conda / mamba:
+(usually faster) if not [GNU `tar`](https://www.gnu.org/software/tar/). If unavailable
+some of these can be installed using conda / mamba:
 
-```bash
+```sh
 conda install -c conda-forge zstandard tar
 ```
 
 Once a simulation is done, you can create the archive using
 
-```bash
+```sh
 cd path/to/sim
 snek-make archive
 ```

docs/how-to/control-fortran-warnings.md

@@ -1,12 +1,12 @@
 # How to control Fortran warnings during compilation
 
-By default Snek5000 suppresses the compilation warnings. This is because
-Nek5000 uses a lot of *legacy tricks* to achieve high performance which
-triggers warnings in modern C and Fortran compilers.
+By default Snek5000 suppresses the compilation warnings. This is because Nek5000 uses a
+lot of *legacy tricks* to achieve high performance which triggers warnings in modern C
+and Fortran compilers.
 
 To display the warnings one should adjust the `verbosity` keyword argument for
-[`Output.update_snakemake_config`](snek5000.output.base.Output.update_snakemake_config). For example
-in your solver's Snakemake file
+[`Output.update_snakemake_config`](snek5000.output.base.Output.update_snakemake_config).
+For example in your solver's Snakemake file
 
 ```{code-block} python
 ---

docs/how-to/export-sans-snek5000.myst.md

@@ -51,8 +51,8 @@ rule source_archive:
         """
 ```
 
-Now execute in an IPython console to generate source code from your templates
-and prescribed parameters.
+Now execute in an IPython console to generate source code from your templates and
+prescribed parameters.
 
 ```{code-cell} python
 ---
@@ -78,7 +78,7 @@ sim.make.exec('source_archive')
 %mv {sim.path_run}/phill_source-archive.tar.gz .
 ```
 
-This archive may now be shared to your colleagues or kept as a standalone
-archive which only depends on Nek5000 for compilation.
+This archive may now be shared to your colleagues or kept as a standalone archive which
+only depends on Nek5000 for compilation.
 
 [snek5000-phill]: https://github.com/snek5000/snek5000-phill/blob/main/src/phill/Snakefile

docs/how-to/history_points.md

@@ -14,7 +14,7 @@ For example, see the
 
 This should be coupled along with a `hpts()` call in `userchk()` subroutine in the
 Nek5000 user file. For more information, see *documentation for
-`params.output.history_points`* in {class}`snek5000.output.base.Output`
+`params.output.history_points`* in {class}`snek5000.output.base.Output`.
 
 ## Loading and plotting
 

docs/how-to/read-write-par-files.md

@@ -1,6 +1,7 @@
 # How to read / write default parameter values from a `*.par` file
 
-Snek5000 is capable of parsing existing `*.par` files. This is shown in the [`snek5000-tgv` example](../examples/snek5000-tgv/src/snek5000_tgv/solver.py),
+Snek5000 is capable of parsing existing `*.par` files. This is shown in the
+[`snek5000-tgv` example](../examples/snek5000-tgv/src/snek5000_tgv/solver.py),
 
 ```{code-block} python
 ---
@@ -26,8 +27,8 @@ class SimulTGV(SimulNek):
 ```
 
 This is useful while porting an existing Nek5000 code as a Snek5000 solver.
-[See the function's
-documentation](snek5000.params.complete_params_from_par_file) for more details.
+[See the function's documentation](snek5000.params.complete_params_from_par_file) for
+more details.
 
 ```{note}
 In Snek5000 we follow a convention of renaming the `*.par` file as `*.par.cfg`

docs/how-to/rebuild-nek.md

@@ -1,9 +1,9 @@
 # How to rebuild Nek5000 libraries and tools
 
 For a fresh git clone of Nek5000 sources, Snek5000 takes care of the build
-automatically. However if your C and Fortran compiler with its related
-toolchain gets an update, or if you change it intentionally you may need to
-recompile Nek5000 libraries again. To do so:
+automatically. However if your C and Fortran compiler with its related toolchain gets an
+update, or if you change it intentionally you may need to recompile Nek5000 libraries
+again. To do so:
 
 ```sh
 cd $NEK_SOURCE_ROOT

docs/how-to/restart.myst.md

@@ -42,7 +42,7 @@ Let's give few examples. We start from a simulation using the `snek5000-phill` s
 1. To restart the simulation in a new session (no compilation needed) from the last
    state file, one can run:
 
-   ```bash
+   ```sh
    snek-restart /path/of/the/simulation --use-start-from -1 --end-time 0.005
    ```
 
@@ -53,14 +53,14 @@ Let's give few examples. We start from a simulation using the `snek5000-phill` s
 1. To restart the simulation in a new session (no compilation needed) from the
    [KTH toolbox] restart files:
 
-   ```bash
+   ```sh
    snek-restart /path/of/the/simulation --use-checkpoint 1 --end-time 0.005
    ```
 
 1. Alternatively, one can restart a simulation in a new directory (new compilation
    needed, first directory unmodified) with:
 
-   ```bash
+   ```sh
    snek-restart /path/of/the/simulation \
        --use-checkpoint 1 --end-time 0.005 --new-dir-results \
        --modify-params "params.nek.stat.av_step=1;"

docs/how-to/run-background-foreground.md

@@ -13,14 +13,14 @@ sim = Simul(params)
 sim.make.exec('run')
 ```
 
-would launch the Snakemake rule `run` (default, if not specified) which
-launches a simulation in the **background** and returns control to the user.
-This is useful in monitoring the simulation. For example see the [tutorial for
-snek5000-cbox](../tuto_cbox).
+would launch the Snakemake rule `run` (default, if not specified) which launches a
+simulation in the **background** and returns control to the user. This is useful in
+monitoring the simulation. For example see the
+[tutorial for snek5000-cbox](../tuto_cbox).
 
-However in HPC clusters you should launch your simulations in the
-**foreground**, thus preventing the job from exiting while the simulation is
-going on. You can also specify number of MPI processes using the `nproc` keyword argument. For example:
+However in HPC clusters you should launch your simulations in the **foreground**, thus
+preventing the job from exiting while the simulation is going on. You can also specify
+number of MPI processes using the `nproc` keyword argument. For example:
 
 ```{code-block} python
 ---

docs/how-to/snek-make.myst.md

@@ -26,7 +26,7 @@ be obtained with (the `!` is for calling a command in Jupyter):
 From a simulation directory, `snek-make -l` lists the available targets. One can do for
 example:
 
-```bash
+```sh
 snek-make cleanall
 snek-make compile
 snek-make show_config

docs/index.rst

@@ -1,4 +1,4 @@
-.. snek5000 documentation master file, created by
+.. snek5000 documentation main file, created by
    sphinx-quickstart on Wed Dec 25 01:55:26 2019.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
@@ -33,14 +33,11 @@ internals rely on FluidSim's core_ to build its API.
    tutorials
    how-to/index.md
 
-User Guide
-----------
-
-.. autosummary::
-   :toctree: _generated/
-   :caption: User Guide
+.. toctree::
+   :maxdepth: 1
+   :caption: User guide & Python API
 
-   snek5000
+   autosum
 
 .. toctree::
    :maxdepth: 1
@@ -54,7 +51,7 @@ User Guide
    Source code on GitHub <https://github.com/snek5000/snek5000>
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/install.rst

@@ -1,13 +1,22 @@
 Installation
 #############
 
-You should always have these environment variables set, pointing to the Nek5000
-source code and the ``bin`` directory within
+Preliminary: setup Nek5000
+==========================
+
+You should always have the environment variable ``NEK_SOURCE_ROOT`` pointing to
+the Nek5000 source code directory:
 
 .. code-block:: bash
 
    export NEK_SOURCE_ROOT="/path/to/Nek5000"
-   export PATH="$PATH:$NEK_SOURCE_ROOT/bin"
+
+.. note::
+
+   You may want to also add the Nek5000 ``bin`` directory in your path (with
+   something like ``export PATH=$PATH:$NEK_SOURCE_ROOT/bin``) to also be able
+   to use Nek5000 directly without Snek5000, but it should not be mandatory for
+   Snek5000.
 
 .. important::