Merge pull request #931 from festim-dev/update-docs

Update docs on fenicsx
festim-dev · Dec 20, 2024 · 0188da3 · 0188da3
2 parents effcbac + 57683e2
commit 0188da3
Show file tree

Hide file tree

Showing 89 changed files with 1,557 additions and 626 deletions.
diff --git a/.github/workflows/doctest.yml b/.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
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -6,7 +6,7 @@
 version: 2
 
 conda:
-  environment: docs/source/environment.yaml
+  environment: docs/environment.yml
 
 build:
   os: "ubuntu-20.04"
@@ -16,13 +16,11 @@ build:
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/source/conf.py
-
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 # formats:
 #    - pdf
 
 # # Optionally declare the Python requirements required to build your docs
-python:
-  install:
-    - method: pip
-      path: .
+# python:
+#    install:
+#    - requirements: docs/requirements.txt
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -0,0 +1,20 @@
+name: festim2-docs
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - fenics-dolfinx
+  - matplotlib==3.7.1
+  - pip>=20.1
+  - sphinx<8 # sphinxcontrib-images is not compatible with sphinx 8
+  - folium
+  - numpy==1.24
+  - tqdm
+  - scifem>=0.2.8
+  - sphinx-design
+  - sphinxcontrib-bibtex
+  - sphinxcontrib-images
+  - sympy
+  - sphinx-book-theme
+  - sphinx-copybutton
+  - pillow
diff --git a/docs/source/Makefile b/docs/source/Makefile
@@ -1,20 +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     = .
-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)
+# 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     = .
+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)
diff --git a/docs/source/_static/style.css b/docs/source/_static/style.css
@@ -0,0 +1,78 @@
+@import url('https://fonts.googleapis.com/css2?family=Lato:ital,wght@0,400;0,700;0,900;1,400;1,700;1,900&family=Open+Sans:ital,wght@0,400;0,600;1,400;1,600&display=swap');
+
+body {
+    font-family: 'Open Sans', sans-serif;
+}
+
+h1 {
+    font-family: "Lato", sans-serif;
+}
+
+pre,
+code {
+    font-size: 100%;
+    line-height: 155%;
+}
+
+/* Main page overview cards */
+
+.sd-card {
+    border-radius: 0;
+    padding: 30px 10px 20px 10px;
+    margin: 10px 0px;
+}
+
+.sd-card .sd-card-header {
+    text-align: center;
+}
+
+.sd-card .sd-card-title {
+    text-align: center;
+}
+
+.sd-card .sd-card-header .sd-card-text {
+    margin: 0px;
+}
+
+.sd-card .sd-card-img-top {
+    height: 52px;
+    width: 52px;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+.sd-card .sd-card-header {
+    border: none;
+    font-size: var(--pst-font-size-h5);
+    font-weight: bold;
+    padding: 2.5rem 0rem 0.5rem 0rem;
+}
+
+
+/* 
+SPHINX-BOOK-THEME HOTFIX (top-right icons): 
+https://github.com/executablebooks/sphinx-book-theme/issues/879 
+*/
+.header-article__inner .header-article-items__end,
+.header-article__inner .header-article-items__start {
+    align-items: start;
+    display: flex;
+    gap: .5rem;
+}
+
+/* 
+SPHINX-BOOK-THEME HOTFIX (right column vertical stretching fix): 
+https://github.com/executablebooks/sphinx-book-theme/issues/879 
+*/
+.toc-entry a.nav-link {
+    padding: .125rem 0 .125rem 1rem;
+}
+
+/* 
+h3 font weight fix (from extra heavy to normal):
+https://github.com/executablebooks/sphinx-book-theme/issues/879 
+*/
+h3 {
+    font-size: 125%;
+    font-weight: normal;
+}
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -1,6 +1,10 @@
 FESTIM API
 ==========
 
+.. warning::
+
+    🔨 This page is under construction. 🔨
+
 
 .. automodule:: festim.boundary_conditions
     :members:

diff --git a/docs/source/bibliography/references.bib b/docs/source/bibliography/references.bib
@@ -0,0 +1,111 @@
+@article{McNabb1963,
+	title        = {{A New Analysis of the Diffusion of Hydrogen in Iron and Ferritic Steels}},
+	author       = {McNabb, A. and Foster, P. K.},
+	year         = 1963,
+	journal      = {Trans. Metall. Soc. AIME},
+	volume       = 227,
+	pages        = 618
+}
+@article{Longhurst1985,
+	title        = {{The soret effect and its implications for fusion reactors}},
+	author       = {Longhurst, G. R.},
+	year         = 1985,
+	journal      = {J. Nucl. Mater.},
+	volume       = 131,
+	number       = 1,
+	pages        = {61--69},
+	issn         = {00223115},
+	url          = {https://linkinghub.elsevier.com/retrieve/pii/0022311585904258}
+}
+@techreport{Pendergrass1976,
+	title        = {{Temperature-dependent ordinary and thermal diffusion of hydrogen isotopes through thermonuclear reactor components}},
+	author       = {Pendergrass, J. H.},
+	year         = 1976,
+	url          = {http://www.osti.gov/servlets/purl/7333557/},
+	institution  = {Los Alamos National Laboratory (LANL)}
+}
+@article{Delaporte-Mathurin2021,
+	title        = {{Influence of interface conditions on hydrogen transport studies}},
+	author       = {Delaporte-Mathurin, R. and Hodille, E. A. and Mougenot, J. and Charles, Y. and {De Temmerman}, G. and Leblond, F. and Grisolia, C.},
+	year         = 2021,
+	journal      = {Nucl. Fusion},
+	volume       = 61,
+	number       = 3,
+	pages        = {036038},
+	issn         = {0029-5515},
+	url          = {https://iopscience.iop.org/article/10.1088/1741-4326/abd95f}
+}
+@phdthesis{Delaporte-Mathurin2022,
+	title        = {{Hydrogen transport in tokamaks : Estimation of the ITER divertor tritium inventory and influence of helium exposure}},
+	author       = {Delaporte-Mathurin, R.},
+	year         = 2022,
+	number       = {2022PA131054},
+	url          = {https://theses.hal.science/tel-04004369},
+	school       = {{Universit{\'e} Paris-Nord - Paris XIII}},
+	keywords     = {Hydrogen ; Finite elements ; Numerical modelling ; Hydrog{\`e}ne ; El{\'e}ments finis ; Mod{\'e}lisation num{\'e}rique},
+	type         = {Theses}
+}
+@article{Schmid2016,
+	title        = {{Diffusion-trapping modelling of hydrogen recycling in tungsten under ELM-like heat loads}},
+	author       = {Schmid, K.},
+	year         = 2016,
+	journal      = {Phys. Scr.},
+	volume       = {T167},
+	pages        = {014025},
+	issn         = {0031-8949},
+	url          = {https://iopscience.iop.org/article/10.1088/0031-8949/T167/1/014025}
+}
+@article{Guterl2019,
+	title        = {Effects of surface processes on hydrogen outgassing from metal in desorption experiments},
+	author       = {Guterl, Jerome and Smirnov, RD and Snyder, P},
+	year         = 2019,
+	journal      = {Nuclear Fusion},
+	publisher    = {IOP Publishing},
+	volume       = 59,
+	number       = 9,
+	pages        = {096042},
+	url          = {https://iopscience.iop.org/article/10.1088/1741-4326/ab280a/meta}
+}
+@article{Pick1985,
+	title        = {A model for atomic hydrogen-metal interactions—application to recycling, recombination and permeation},
+	author       = {Pick, MA and Sonnenberg, K},
+	year         = 1985,
+	journal      = {Journal of Nuclear Materials},
+	publisher    = {Elsevier},
+	volume       = 131,
+	number       = {2-3},
+	pages        = {208--220},
+	url          = {https://www.sciencedirect.com/science/article/abs/pii/0022311585904593}
+}
+@article{Hodille2017,
+	title        = {Simulations of atomic deuterium exposure in self-damaged tungsten},
+	author       = {Hodille, EA and Zalo{\v{z}}nik, A and Markelj, S and Schwarz-Selinger, T and Becquart, CS and Bisson, R{\'e}gis and Grisolia, Christian},
+	year         = 2017,
+	journal      = {Nuclear Fusion},
+	publisher    = {IOP Publishing},
+	volume       = 57,
+	number       = 5,
+	pages        = {056002},
+	url          = {https://iopscience.iop.org/article/10.1088/1741-4326/aa5aa5/meta}
+}
+@article{Schmid2021,
+	title        = {On the use of recombination rate coefficients in hydrogen transport calculations},
+	author       = {Schmid, K and Zibrov, M},
+	year         = 2021,
+	journal      = {Nuclear Fusion},
+	publisher    = {IOP Publishing},
+	volume       = 61,
+	number       = 8,
+	pages        = {086008},
+	url          = {https://iopscience.iop.org/article/10.1088/1741-4326/ac07b2/meta}
+}
+@article{Hamamoto2020,
+	title        = {Comprehensive modeling of hydrogen transport and accumulation in titanium and zirconium},
+	author       = {Hamamoto, Yoshiki and Uchikoshi, Takeru and Tanabe, Katsuaki},
+	year         = 2020,
+	journal      = {Nuclear Materials and Energy},
+	publisher    = {Elsevier},
+	volume       = 23,
+	pages        = 100751,
+	url          = {https://www.sciencedirect.com/science/article/pii/S2352179120300272}
+}