documentation addressing Joss review issue 186

[jotelha]

Here, I will address the missing

• Electrochemistry module documentation
  • PNP solver documentation
  • sampling documentation
  • Fenics integration documentation
  • steric correction documentation
• CLI documentation

pointed out in #186
and in the Package-related Comments 2. of openjournals/joss-reviews#5668 (comment)

[jotelha]

Before this is merged, I want to point out:

• with the good old setup.py, I had the electrochemistry module's shell commands installed only if explicitly desired by specifying the extra [cli], e.g. pip install matscipy[cli]. I think this is not possible with the current pyproject.toml / meson combination. The [cli] extra still exists, but the CLI scripts always get installed, no matter whether the extra has been specified or not. I have added a note on that circumstance within the pyproject.toml at

  matscipy/pyproject.toml

  Lines 50 to 70 in 9456d8c

  	# https://packaging.python.org/en/latest/specifications/pyproject-toml/#entry-points
  	[project.scripts]
  	# With setuptools, specifying entry points like this in setup.py
  	# ...
  	# entry_points={
  	# 'console_scripts': [
  	# 'c2d = matscipy.cli.electrochemistry.c2d:main [cli]',
  	# 'pnp = matscipy.cli.electrochemistry.pnp:main [cli]',
  	# 'stericify = matscipy.cli.electrochemistry.stericify:main [cli]'
  	# ],
  	# },
  	# ...
  	# resulted in optional CLI scripts installed only if the extra [cli] had been
  	# explicitly requested, e.g. via
  	# pip install matscipy[cli]
  	# (see https://github.com/libAtoms/matscipy/blob/92dd490a3c2c71edc5d0018487afbee5f2273730/setup.py#L302-L319)
  	# With pyproject.toml and meson as build system, the console scripts are
  	# always installed, even if they are specified as extra-dependent as done here.
  	continuous2discrete = "matscipy.cli.electrochemistry.continuous2discrete_cli:main [cli]"
  	poisson-nernst-planck = "matscipy.cli.electrochemistry.poisson_nernst_planck_solver_cli:main [cli]"
  	stericify = "matscipy.cli.electrochemistry.stericify_cli:main [cli]"

  .
• as desired in [JOSS Review] Documentation  #186, the electrochemistry module documentation includes a page on the fenics integration. This means building the documentation requires fenics. I have added the required lines

  matscipy/.github/workflows/documentation.yml

  Lines 28 to 34 in 9456d8c

  	# needs fenics to build fenics integration documentation snippet
  	- name: install_fenics
  	run: |
  	sudo apt-get install -y --no-install-recommends software-properties-common
  	sudo add-apt-repository -y ppa:fenics-packages/fenics
  	sudo apt-get update -qy
  	sudo apt-get install -y fenics python3-dolfin python3-mshr

  to .github/workflows/documentation.yml. This means, however, that anyone who wants to build the whole documentation locally will need fenics installed as well.
• added a few lines

  matscipy/docs/conf.py

  Lines 299 to 308 in 9456d8c

  	# The following makes mystnb convert notebooks with jupytext
  	# before execution and documentation rendering. This allows
  	# storing notebooks in properly versionable text formats, e.g.
  	# the percent format,
  	# https://jupytext.readthedocs.io/en/latest/formats-scripts.html#the-percent-format
  	# instead of .ipynb. Also see
  	# https://myst-nb.readthedocs.io/en/latest/authoring/custom-formats.html#using-jupytext
  	nb_custom_formats = {
  	".py": ["jupytext.reads", {"fmt": "py:percent"}]
  	}

  to the sphinx configuration to allow storing notebooks in the docs in properly versionable text formats instead of .ipynb

[jotelha]

Added the possibility to quickly generate a spelling report for finding typos with make spelling within the docs folder.

[jotelha]

If merged, I will remove the https://github.com/libAtoms/matscipy/blob/master/.github/workflows/tests_fenics.yml workflow, as building the documentation is essentially running equivalent example notebooks.