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,19 +26,18 @@ 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.
 
-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.
 
 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.
@@ -57,10 +56,9 @@ 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

@@ -8,14 +8,29 @@ 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>`_.
-
+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 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/festim-dev/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/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.
+
+
+--------------
+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,12 +14,13 @@ 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.
 
@@ -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: :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.
+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 (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
+A 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