Merge pull request #2 from LLNL/readthedocs

Readthedocs merge

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Build docs
+run-name: ${{ github.actor }} is building docs
+on: [push]
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+    container:
+      image: firedrakeproject/firedrake-docdeps:latest
+      options: --user root
+      volumes:
+        - ${{ github.workspace }}:/home/firedrake/output
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install checkedout Firedrake
+        run: |
+          . /home/firedrake/firedrake/bin/activate
+          python -m pip install -e .
+          pip install sphinx-rtd-theme
+      - name: Build docs
+        run: |
+          . /home/firedrake/firedrake/bin/activate
+          cd docs
+          make html
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          name: github-pages
+          path: /__w/echemfem/echemfem/docs/build/html
+          retention-days: 1
+  deploy:
+    name: Deploy Github pages
+    needs: build_docs
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: http://llnl.github.io/echemfem
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==7.1.2
+sphinx-rtd-theme==1.3.0rc1

docs/source/api.rst

@@ -0,0 +1,18 @@
+API
+===
+
+EchemSolver class
+-----------------
+
+.. autoclass:: echemfem.EchemSolver
+   :members:
+
+Utility meshes
+--------------
+These are boundary layer meshes, which are modified versions of :func:`firedrake.utility_meshes.IntervalMesh` and :func:`firedrake.utility_meshes.RectangleMesh`.
+
+.. automodule:: echemfem.utility_meshes
+   :members:
+
+.. toctree::
+   :hidden:

docs/source/conf.py

@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'EchemFEM'
+copyright = '2023, Thomas Roy'
+author = 'Thomas Roy'
+
+release = '0.1'
+version = '0.0.1'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    'firedrake': ('https://firedrakeproject.org/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'

docs/source/index.rst

@@ -0,0 +1,27 @@
+Welcome to EchemFEM's documentation!
+====================================
+
+**EchemFEM** is a Python library based on
+`Firedrake <https://www.firedrakeproject.org/download.html>`_, providing Finite
+Element solvers for electrochemical transport.
+
+Check out the :doc:`quickstart` section for further information, including
+the :ref:`installation` of the package.
+
+.. note::
+
+   This project is under active development.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart
+   user_guide/index
+
+.. toctree::
+   :titlesonly:
+
+   api

docs/source/quickstart.rst

@@ -0,0 +1,33 @@
+Quickstart Guide
+================
+
+.. _installation:
+
+Installation
+------------
+
+First, please install the open-source finite element library `Firedrake <https://www.firedrakeproject.org/download.html>`_.
+
+EchemFEM is hosted on `GitHub <https://github.com/LLNL/echemfem>`_, and should be cloned from there.
+
+To use EchemFEM, first install it using pip within the Firedrake virtual environment:
+
+.. code-block:: console
+
+   (firedrake) $ pip install -e .
+
+To test your installation, you can run the tests in `echemfem/tests <https://github.com/LLNL/echemfem/examples>`_ using pytest.
+This can take some time, so it is probably enough to run this test:
+
+.. code-block:: console
+
+   (firedrake) $ pytest test_advection_diffusion_migration.py
+
+Alternatively, you can run some of the examples below.
+
+Running Examples
+----------------
+
+Several examples can be found in `echemfem/examples <https://github.com/LLNL/echemfem/examples>`_.
+
+

docs/source/user_guide/boundary_conditions.rst

@@ -0,0 +1,10 @@
+Boundary Conditions
+===================
+
+The boundary conditions need to set through
+:meth:`echemfem.EchemSolver.set_boundary_markers`, which sets a dictionary
+containing boundary condition names and their corresponding boundary id.
+
+.. note::
+
+   This page is under construction.

docs/source/user_guide/conc_params.rst

@@ -0,0 +1,18 @@
+Concentration Parameters
+========================
+
+The physical parameters of each species need to be provided
+:attr:`echemfem.EchemSolver.conc_params`, a list containing one dictionary for
+each species. Below is a list of different keys that can appear in each dictionary
+
+* :Key: ``"name"``
+  :Type: :py:class:`str`
+  :Description: Species name. E.g. ``"CO2"``
+  :Uses: Name of field in pvd output. Used to get index in the solution vector.
+* :Key: ``"bulk"``
+  :Type: :py:class:`float`, firedrake expression
+  :Description: Concentration at the "bulk". This value is used in :meth:`echemfem.EchemSolver.setup_solver`
+
+.. note::
+
+   This page is under construction.

docs/source/user_guide/echem_params.rst

@@ -0,0 +1,11 @@
+Electrochemical Parameters
+==========================
+
+The parameters of each charge-transfer reaction can be provided through
+:attr:`echemfem.EchemSolver.echem_params`, a list containing one dictionary for
+each charge-transfer reaction. Below is a list of different keys that can
+appear in each dictionary
+
+.. note::
+
+   This page is under construction.

docs/source/user_guide/index.rst

@@ -0,0 +1,22 @@
+User Guide
+==========
+
+This guide will help a user understand existing examples, and design new ones.
+
+The first step of writing an EchemFEM script is to import the ``EchemSolver`` class:
+
+.. code-block::
+
+   from echemfem import EchemSolver
+
+This is an abstract class, which we will use as the base class for a specific model.
+To create a customized solver, the user should set the following inputs:
+
+.. toctree::
+   :maxdepth: 2
+
+   conc_params
+   physical_params
+   boundary_conditions
+   echem_params
+

docs/source/user_guide/physical_params.rst

@@ -0,0 +1,11 @@
+Physical Parameters
+===================
+
+The general physical parameters need to be provided in
+:attr:`echemfem.EchemSolver.physical_params`, a dictionary. Below is a list of
+different keys that can appear in each dictionary
+
+
+.. note::
+
+   This page is under construction.