Update docs on fenicsx

.github/workflows/doctest.yml

@@ -0,0 +1,21 @@
+name: Documentation test
+
+on: [push, pull_request]
+
+jobs:
+  docbuild:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Conda
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          activate-environment: festim2-docs
+          environment-file: docs/environment.yml
+
+      - name: Doc Tests
+        shell: bash -l {0}
+        run: sphinx-build -b doctest docs/source docs/_build/doctest

docs/environment.yml

@@ -0,0 +1,19 @@
+name: festim2-docs
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - fenics-dolfinx
+  - matplotlib==3.7.1
+  - pip>=20.1
+  - sphinx==7
+  - folium
+  - numpy==1.24
+  - pip:
+      - sympy
+      - sphinx_book_theme==1.1.2
+      - sphinx-design==0.5.0
+      - sphinxcontrib-bibtex
+      - sphinx-copybutton
+      - pillow
+      - sphinxcontrib-images

docs/source/api/index.rst

@@ -1,6 +1,7 @@
 FESTIM API
 ==========
 
+WIP
 
 .. automodule:: festim.boundary_conditions
     :members:

docs/source/devguide/index.rst

@@ -22,61 +22,106 @@ And/or contribute to the source code by:
 * Fixing bugs
 * Implementing new features
 
-.. _contributing to the code:
-
 ------------------------
 Contributing to the code
 ------------------------
 
-.. admonition:: Tip
-   :class: tip
+For complete information on contributions with GitHub see this guide on `GitHub <https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project>`_.
+
+.. tip::
+
+   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 relatively easy to tackle and perfect for newcomers.
+
+#. `Fork the repository <https://github.com/festim-dev/FESTIM/fork>`_
+
+   By forking the repository, you create a copy where you can safely make changes.
+
+#. Clone your fork
+
+   .. code-block:: bash
+
+      git clone https://github.com/[your_username]/FESTIM
+
+   Remember to replace ``[your_username]`` with your GitHub username.
+
+#. Make your changes
+
+   Commit your changes locally and push them to your fork.
+
+   .. code-block:: bash
+
+      git add [modified files]
+      git commit -m "Your commit message"
+      git push
+
+#. Test your code
+
+   If you are adding new features or fixing bugs, it is important to test your code.
+   See :ref:`Test suite` for more information.
+
+#. Format your code using `Black <https://github.com/psf/black>`_.
+
+   The source code of FESTIM is formated with the Black code formatter. Using of a unified code style simplifies the code review
+   and increases its readability. See :ref:`Code formatting` for more information.
 
-   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>`_.
+#. Optional: Build the documentation
 
-   These issues are usually fairly easy to tackle and therefore perfect for newcomers.
+   You may want to build the documentation to see if your changes are correctly reflected or if you are updating the docs.
+   See :ref:`Documentation guide` for more information.
 
-1) `Fork the repository <https://github.com/RemDelaporteMathurin/FESTIM/fork>`_
+#. `Open a PR <https://github.com/festim-dev/FESTIM/compare>`_
 
-By forking the repository, you create a copy of it where you can safely make changes.
+#. Wait for a :ref:`maintainer<Maintainers>` to review your PR
 
-2) Make your changes
-3) `Open a PR <https://github.com/RemDelaporteMathurin/FESTIM/compare>`_
-4) Wait for a maintainer to review your PR
+   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.
 
-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.
-The time before the review will depend on the maintainers' availability.
+#. When everything is in order, the maintainers will merge your PR!
 
-5) When everything is in order, the maintainers will merge your PR!
+-----------
+Maintainers
+-----------
+
+The maintainers are the people who have the right to merge PRs to the repository.
+They consist of the following individuals:
+
+- Remi Delaporte-Mathurin (`@RemDelaporteMathurin <https://github.com/RemDelaporteMathurin>`_)
+- James Dark (`@jhdark <https://github.com/jhdark>`_)
+- Vladimir Kulagin (`@KulaginVladimir <https://github.com/KulaginVladimir>`_)
+
+The project lead is Remi Delaporte-Mathurin.
 
 ----------
 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/fenicsx/test>`_ at the root of the FESTIM repository.
+
+You need to have the right dependencies installed to test your code (see :ref:`installation<Installation>`).
+
+.. note::
 
-.. admonition:: Tip
-   :class: tip
+   Make sure to install ``pytest`` to run the test suite locally:
 
-   If you have installed the FEniCS Anaconda python package, make sure to install pytest to run the test suite locally:
+   .. code-block:: bash
 
       pip install pytest
 
    And then run the tests using:
 
+   .. code-block:: bash
+
       pytest test/
 
-   Although if you are running the Docker image, pytest packages are prebuilt, thus use the command:
-
-      pytest-3 test/
-
-
 Whenever contributors open a PR, **the tests must pass** in order for the PR to be merged in.
 
 In some cases, new tests need to be written to account for more use cases or to catch bugs that weren't previously caught.
@@ -87,7 +132,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.
@@ -104,13 +149,116 @@ 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.
    | 
    | It is also beneficial to discuss with the community on how this new feature would be used.
 
-#. :ref:`Make your changes<contributing to the code>`
+#. :ref:`Make your changes<contributing to the code>`. Don't forget to :ref:`adapt the documentation <Documentation guide>` if necessary.
 
 #. Write a test to test your feature
+
+#. Open a PR
+
+
+----------------
+Code formatting
+----------------
+
+Before merging your PR, the modified scripts should be formatted to maintain the consistency of the coding style. FESTIM is formatted using 
+`Black <https://github.com/psf/black>`_. To install Black, run the following command:
+
+.. code-block:: bash
+
+   pip install black
+
+After the installation, you can format a file using:
+
+.. code-block:: bash
+
+   black my_script.py
+
+Alternatively, you can format all files in the current directory with:
+
+.. code-block:: bash
+
+   black .
+
+
+If you use Visual Studio Code, you can install the `extension <https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter>`_ 
+with support for the Black formatter. Then, you can set Black as a default formatter for python and enable formatting "on save" for your code. 
+
+-------------------
+Documentation guide
+-------------------
+
+The documentation is a crucial part of the project. It is the first thing users will see when they want to use FESTIM.
+It is important to keep it up to date and clear.
+
+The documentation is written in `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ and is located in the `docs folder <https://github.com/festim-dev/FESTIM/tree/fenicsx/docs>`_ at the root of the FESTIM repository.
+
+The documentation is built using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+
+To build the documentation locally, you can use the following command:
+
+.. code-block:: bash
+
+   cd docs/source
+   make html
+
+This will generate the documentation in the `docs/source/_build/html` folder.
+You can then open the `index.html` file in your browser to see the documentation.
+To remove everything and start from scratch, you can use the following command:
+
+.. code-block:: bash
+
+   make clean
+
+Alternatively, you can use the following command to build the documentation in one line:
+
+.. code-block:: bash
+
+   cd docs
+   sphinx-build -b html source build
+
+.. note::
+
+   Make sure to have the right dependencies installed. You can create a new conda environment with the following command:
+
+   .. code-block:: bash
+
+      conda env create -f docs/environment.yml
+
+   This will create a new environment called `festim2-docs` with all the necessary dependencies.
+   Activate it using:
+
+   .. code-block:: bash
+
+      conda activate festim2-docs
+
+The documentation is hosted on `Read the Docs <https://readthedocs.org/>`_ and is automatically updated when a new commit is pushed to the repository or to a Pull Request.
+
+.. note::
+
+   The documentation is built using the `sphinx_book_theme <https://sphinx-book-theme.readthedocs.io/en/latest/>`_ theme.
+
+When contributing to the documentation, make sure to:
+
+#. Write clear and concise documentation
+#. Use the right syntax
+#. Update the documentation when new features are added
+#. Test the documentation using:
+
+.. code-block:: bash
+
+   cd docs/source
+   make doctest
+
+or using: 
+
+.. code-block:: bash
+
+   cd docs
+   sphinx-build -b doctest source build

docs/source/examples.rst

@@ -1,4 +1,4 @@
 Examples
 ********
 
-You can find examples and tutorials on the `FESTIM workshop <https://github.com/RemDelaporteMathurin/FESTIM-workshop>`_.
+WIP