Improve documentation for developers

snek5000 · Dec 19, 2022 · b4ccb98 · b4ccb98
1 parent ecdbf4f
commit b4ccb98
Show file tree

Hide file tree

Showing 7 changed files with 82 additions and 23 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,35 +11,31 @@ 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
-source activate.sh
 ```
 
-Now you should setup a Python environment. There are two ways to do this (and it has to
-be done only once):
-
-- Using `venv`
-
-  ```sh
-  python -m venv venv
-  source venv/bin/activate
-  ```
+Now you should setup a Python environment. Here, we show how to do it with the package
+`venv`:
 
-- Using `conda`
-
-  ```sh
-  conda env create -n env-snek5000
-  conda activate env-snek5000
-  ```
+```sh
+python -m venv venv
+source venv/bin/activate
+```
 
 Finally, to install in development mode:
 
 ```sh
 pip install pip-tools nox
-nox -s pip-sync
+nox -s sync
+```
+
+````{note}
+From the root directory of the project, one can then activate the dev
+environment with:
+```sh
+source activate.sh
 ```
+````
 
 ## General guidelines
 
@@ -70,6 +66,8 @@ nox -s pip-sync
 
   to activate debugging logs and longer tests.
 
+See also our [](./dev/index.rst).
+
 ## Vim
 
 Vim users could benefit by setting:

diff --git a/docs/dev/edit_tutorials.md b/docs/dev/edit_tutorials.md
@@ -9,4 +9,8 @@ Notebook". Saving the notebook in the Jupyter interface should also saved the My
 
 Note that some files are coupled with a Python script in `docs/examples/scripts`.
 
+```{warning}
+One has to delete the `.ipynb` files before building the whole documentation with Sphinx.
+```
+
 [jupytext]: https://jupytext.readthedocs.io
diff --git a/docs/dev/howto_doc.md b/docs/dev/howto_doc.md
@@ -0,0 +1,21 @@
+# How to build the documentation
+
+## Old school
+
+With a development environment and from the `docs` directory:
+
+```sh
+make cleanall
+make
+```
+
+## With `nox`
+
+With `nox` installed and from the root directory of the repository:
+
+```sh
+# first time (this creates the environment)
+nox -s docs
+# when the environment has been created
+nox -s docs -r --no-install
+```
diff --git a/docs/dev/howto_test.md b/docs/dev/howto_test.md
@@ -0,0 +1,34 @@
+# How to run the tests
+
+## As in the CI with `nox`
+
+Our tests are run on Github Actions with
+
+```sh
+nox --session tests-cov -- -v --runslow --cov-report=xml
+```
+
+So the following command can be useful
+
+```sh
+# first time (creation of the environment)
+nox -s tests-cov
+# after the creation of the environment
+nox -s tests-cov -r --no-install
+nox -s tests-cov -r --no-install -- -v --runslow
+```
+
+With the session `tests` instead of `tests-cov`, no coverage report is created.
+
+## Manually without `nox`
+
+Of course, if can be very useful to launch some tests manually. With the test or dev
+dependencies installed, one can run for example:
+
+```sh
+pytest tests
+pytest --runslow tests/test_restart.py
+pytest --runslow tests/test_restart.py::test_restart_new_dir_results
+pytest -h | grep pdb
+pytest tests/test_files.py --pdb --pdbcls=IPython.terminal.debugger:TerminalPdb
+```
diff --git a/docs/dev/index.rst b/docs/dev/index.rst
@@ -28,10 +28,12 @@ To install for development, execute::
    phys_fields
    nek
    roadmap
-   release
 
 .. toctree::
    :maxdepth: 1
    :caption: How to for developers / maintainers of Snek5000 package
 
+   howto_test.md
+   howto_doc.md
    edit_tutorials.md
+   release.md
diff --git a/docs/dev/release.md b/docs/dev/release.md
@@ -1,4 +1,4 @@
-# Release checklist for maintainers
+# How to release
 
 ## Via GitHub Actions
 

diff --git a/docs/how-to/templates.md b/docs/how-to/templates.md
@@ -16,8 +16,8 @@ code:
 - These methods are called in a method
   {func}`snek5000.output.base.Output.post_init_create_additional_source_files` which
   uses the class attributes `template_box`, `template_size` and `template_makefile_usr`.
-  These attributes are defined in the solvers, for example for `snek5000-tgv` in the file
-  `snek5000_tgv.output`:
+  These attributes are defined in the solvers, for example for `snek5000-tgv` in the
+  file `snek5000_tgv.output`:
 
   ```{eval-rst}
   .. literalinclude:: ../examples/snek5000-tgv/src/snek5000_tgv/output.py