Improve docs

CITATION.cff

@@ -10,7 +10,7 @@ authors:
   - given-names: James
     family-names: Dark
 
-repository-code: 'https://github.com/RemDelaporteMathurin/FESTIM'
+repository-code: 'https://github.com/festim-dev/FESTIM'
 version: 0.8.1
 preferred-citation:
   authors:

docs/source/api/settings.rst

@@ -1,3 +1,5 @@
+.. _settings_api:
+
 Settings
 ========
 

docs/source/conf.py

@@ -43,6 +43,8 @@
     "matplotlib.sphinxext.plot_directive",
 ]
 
+napoleon_use_ivar = True  # needed to correctly format class attributes
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/source/devguide/index.rst

@@ -26,22 +26,21 @@ And/or contribute to the source code by:
 Contributing to the code
 ------------------------
 
-.. admonition:: Tip
-   :class: tip
+.. tip::
 
-   If you're a beginner, look for `issues tagged with "Good first issue" <https://github.com/RemDelaporteMathurin/FESTIM/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_.
+   If you're a beginner, look for `issues tagged with "Good first issue" <https://github.com/festim-dev/FESTIM/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_.
 
-   These issues are usually fairly easy to tackle and therefore perfect for newcomers.
+   These issues are usually relatively easy to tackle and perfect for newcomers.
 
-1) `Fork the repository <https://github.com/RemDelaporteMathurin/FESTIM/fork>`_
+1) `Fork the repository <https://github.com/festim-dev/FESTIM/fork>`_
 
-By forking the repository, you create a copy of it where you can safely make changes.
+By forking the repository, you create a copy where you can safely make changes.
 
 2) Make your changes
-3) `Open a PR <https://github.com/RemDelaporteMathurin/FESTIM/compare>`_
+3) `Open a PR <https://github.com/festim-dev/FESTIM/compare>`_
 4) Wait for a maintainer to review your PR
 
-Before merging your changes, they have to be reviewed. During the review, we make sure the changes don't break anything and eventually propose/request improvements.
+Before merging your changes, they have to be reviewed. We ensure the changes don't break anything during the review and eventually propose/request improvements.
 The time before the review will depend on the maintainers' availability.
 
 5) When everything is in order, the maintainers will merge your PR!
@@ -50,17 +49,16 @@ The time before the review will depend on the maintainers' availability.
 Test suite
 ----------
 
-FESTIM uses continuous integration (CI) to ensure code quality and eliminate as much bugs as possible.
+FESTIM uses continuous integration (CI) to ensure code quality and eliminate as many bugs as possible.
 
 In a nutshell, every time a change is pushed to the repository (or to a PR), a suite of tests is automatically triggered.
 This is to make sure the changes don't break existing functionalities.
 It is also very useful to catch bugs that developers could have missed.
 Click `here <https://www.atlassian.com/continuous-delivery/continuous-integration>`_ for more information on CI.
 
-All the tests can be found in the `test folder <https://github.com/RemDelaporteMathurin/FESTIM/tree/main/test>`_ at the root of the FESTIM repository.
+All the tests can be found in the `test folder <https://github.com/festim-dev/FESTIM/tree/main/test>`_ at the root of the FESTIM repository.
 
-.. admonition:: Tip
-   :class: tip
+.. note::
 
    If you have installed the FEniCS Anaconda python package, make sure to install pytest to run the test suite locally:
 
@@ -85,7 +83,7 @@ Debugging
 
 When you find a bug in the code, there are several steps to follow to make things easier for maintainers.
 
-#. | `Raise an issue <https://github.com/RemDelaporteMathurin/FESTIM/issues/new/choose>`_
+#. | `Raise an issue <https://github.com/festim-dev/FESTIM/issues/new/choose>`_
    |
    | This is important to keep track of things.
    | The issue is a place to talk about the bug, troubleshoot users and sometimes find workarounds.
@@ -102,7 +100,7 @@ When you find a bug in the code, there are several steps to follow to make thing
 Implementing a new feature
 --------------------------
 
-#. | `Raise an issue <https://github.com/RemDelaporteMathurin/FESTIM/issues/new/choose>`_
+#. | `Raise an issue <https://github.com/festim-dev/FESTIM/issues/new/choose>`_
    |
    | Before spending time implementing a new great feature, it is better to open an issue first to discuss with the maintainers.
    | For all you know, someone is already working at implementing it and all your time would be spent for nothing.

docs/source/userguide/beginners_guide.rst

@@ -6,16 +6,31 @@ A beginner's guide to FESTIM
 What do I need to know?
 -----------------------
 
-To make the most out of FESTIM, a basic knowledge of `Python <https://www.learnpython.org/>`_ is required.
-
-Depending on how you install FESTIM, new users should familiarise with either `Docker <https://www.docker.com/>`_ or `Conda <https://anaconda.org/>`_.
-
-FESTIM is under version control with `git <https://git-scm.com/>`_. Even though users don't need git to install FESTIM, it is convenient to have a basic understanding of how it works. You can fin `git turorials <https://git-scm.com/doc>`_ to help you getting started. The `FESTIM source code <https://github.com/RemDelaporteMathurin/FESTIM>`_ is hosted on GitHub. It is recommended to sign up for free to GitHub in order to receive the latest updates, follow the development and submit `bug reports <https://github.com/RemDelaporteMathurin/FESTIM/issues/new/choose>`_.
+Basic knowledge of `Python <https://www.learnpython.org/>`_ is required to make the most out of FESTIM.
 
+New users should familiarise themselves with `Conda <https://anaconda.org/>`_.
 
+FESTIM is under version control with `git <https://git-scm.com/>`_. Even though users don't need git to install FESTIM, it is convenient to understand how it works. You can find `git tutorials <https://git-scm.com/doc>`_ to help you getting started. The `FESTIM source code <https://github.com/festim-dev/FESTIM>`_ is hosted on GitHub. Signing up for free to GitHub is recommended to receive the latest updates, follow the development and submit `bug reports <https://github.com/festim-dev/FESTIM/issues/new/choose>`_.
 
 ----------------------
 Where can I find help?
 ----------------------
 
-If you're having an issue, the best way to find help is to join the `FESTIM discourse <https://festim.discourse.group>`_. Engage in discussions, ask questions, and connect with other users. This is a collaborative space where you can share your experiences and seek assistance.
+If you're having an issue, the best way to find help is to join the `FESTIM discourse <https://festim.discourse.group>`_. Engage in discussions, ask questions, and connect with other users. This collaborative space allows you to share your experiences and seek assistance.
+
+
+--------------
+Install FESTIM
+--------------
+
+Follow the :ref:`installation instructions<Install>` to install FESTIM on your computer.
+
+------------------------
+Your first FESTIM script
+------------------------
+
+
+Follow `this tutorial <https://github.com/festim-dev/FESTIM-workshop/blob/main/tasks/task1.ipynb>`_ to learn how
+to run a simple 1D diffusion problem in steady state with an homogeneous temperature, a volumetric source of hydrogen,
+and the concentration fixed at zero at boundaries.
+

docs/source/userguide/boundary_conditions.rst

@@ -14,14 +14,15 @@ These BCs can be used for heat transfer or hydrogen transport simulations.
 Imposing the solution
 ^^^^^^^^^^^^^^^^^^^^^
 
+The value of solutions (concentration, temperature) can be imposed on boundaries with :class:`festim.DirichletBC`: 
+
 .. code-block:: python
 
     my_bc = DirichletBC(surfaces=[2, 4], value=10, field=0)
 
-.. admonition:: Note
-   :class: tip
+.. note::
 
-    Here, we set :code:`field=0` to specify this BC applies to the mobile hydrogen concentration. :code:`1` would stand for the trap 1 concentration and :code:`"T"` for temperature.
+    Here, we set :code:`field=0` to specify that this BC applies to the mobile hydrogen concentration. :code:`1` would stand for the trap 1 concentration, and :code:`"T"` for temperature.
 
 The `value` argument can be space and time dependent by making use of the FESTIM variables ``x``, ``y``, ``z`` and ``t``:
 
@@ -42,7 +43,7 @@ To use more complicated mathematical expressions, you can use the sympy package:
 
 - CustomDirichlet
 
-The value of the concentration field can be temperature-dependent (useful when dealing with heat-transfer solvers) with :code:`CustomDirichlet`:
+The value of the concentration field can be temperature-dependent (useful when dealing with heat-transfer solvers) with :class:`festim.CustomDirichlet`:
 
 .. code-block:: python
 
@@ -54,7 +55,7 @@ The value of the concentration field can be temperature-dependent (useful when d
 Imposing the flux
 ^^^^^^^^^^^^^^^^^
 
-When the flux needs to be imposed on a boundary, use the :code:`FluxBC` class.
+When the flux needs to be imposed on a boundary, use the :class:`festim.FluxBC` class.
 
 
 .. code-block:: python
@@ -81,7 +82,7 @@ Some BCs are specific to hydrogen transport. FESTIM provides a handful of conven
 Recombination flux
 ^^^^^^^^^^^^^^^^^^
 
-Recombination flux can be set on boundaries as: :math:`Kr \, c_\mathrm{m}^n`.
+A recombination flux can be set on boundaries as follows: :math:`Kr \, c_\mathrm{m}^n` (See :class:`festim.RecombinationFlux`).
 Where :math:`Kr` is the recombination coefficient, :math:`c_\mathrm{m}` is the mobile hydrogen concentration and :math:`n` is the recombination order.
 
 .. code-block:: python
@@ -92,7 +93,7 @@ Where :math:`Kr` is the recombination coefficient, :math:`c_\mathrm{m}` is the m
 Dissociation flux
 ^^^^^^^^^^^^^^^^^^
 
-Dissociation flux can be set on boundaries as: :math:`Kd \, P`.
+Dissociation flux can be set on boundaries as: :math:`Kd \, P` (see :class:`festim.DissociationFlux`).
 Where :math:`Kd` is the dissociation coefficient, :math:`P` is the partial pressure of hydrogen.
 
 .. code-block:: python
@@ -103,7 +104,7 @@ Where :math:`Kd` is the dissociation coefficient, :math:`P` is the partial press
 Sievert's law of solubility
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Impose the mobile concentration of hydrogen as :math:`c_\mathrm{m} = S(T) \sqrt{P}` where :math:`S` is the Sievert's solubility and :math:`P` is the partial pressure of hydrogen.
+Impose the mobile concentration of hydrogen as :math:`c_\mathrm{m} = S(T) \sqrt{P}` where :math:`S` is the Sievert's solubility and :math:`P` is the partial pressure of hydrogen (see :class:`festim.SievertsBC`).
 
 .. code-block:: python
 
@@ -115,7 +116,7 @@ Impose the mobile concentration of hydrogen as :math:`c_\mathrm{m} = S(T) \sqrt{
 Henry's law of solubility
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Similarily, the mobile concentration can be set from Henry's law of solubility :math:`c_\mathrm{m} = K_H P` where :math:`K_H` is the Henry solubility.
+Similarly, the mobile concentration can be set from Henry's law of solubility :math:`c_\mathrm{m} = K_H P` where :math:`K_H` is the Henry solubility (see :class:`festim.HenrysBC`).
 
 
 .. code-block:: python
@@ -127,28 +128,8 @@ Similarily, the mobile concentration can be set from Henry's law of solubility :
 Plasma implantation approximation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-A plasma implantation can be approximated by:
-
-.. math::
-
-    c_\mathrm{m} = \frac{\varphi_\mathrm{imp} \, R_p}{D} + \sqrt{\frac{\varphi_\mathrm{imp} + Kd \cdot P}{Kr}}
-
-Where :math:`\varphi_\mathrm{imp}` is the implanted flux, :math:`R_p` is the implantation depth, :math:`D` is the diffusion coefficient, :math:`Kd` is the dissociation coefficient, :math:`P` is the partial pressure of hydrogen,  and :math:`Kr` is the recombination coefficient.
-
-When :math:`P = 0`:
-
-.. math::
-    c_\mathrm{m} = \frac{\varphi_\mathrm{imp} \, R_p}{D} + \sqrt{\frac{\varphi_\mathrm{imp}}{Kr}}
-
-Moreover, assuming an instantaneous recombination :math:`Kr = \infty`:
-
-.. math::
-    c_\mathrm{m} = \frac{\varphi_\mathrm{imp} \, R_p}{D}
-
-.. admonition:: Note
-   :class: tip
+Plasma implantation can be approximated by a Dirichlet boundary condition with the class :class:`festim.ImplantationDirichlet` . Refer to the :ref:`theory` section for more details.
 
-    Refer to the :ref:`theory` section for more details.
 
 .. code-block:: python
 
@@ -166,7 +147,7 @@ Heat transfer BCs
 -----------------
 
 
-A convective heat flux can be set as :math:`\mathrm{flux} = - h (T - T_\mathrm{ext})`.
+A convective heat flux can be set as :math:`\mathrm{flux} = - h (T - T_\mathrm{ext})` (see :class:`festim.ConvectiveFlux`).
 
 .. code-block:: python