Skip to content

Commit e8a8125

Browse files
indiamaiindiamai
authored
Documentation (#7)
Re-theme docs and expand them.
1 parent 3277ba8 commit e8a8125

26 files changed

+327
-70
lines changed

‎Makefile‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,10 @@ ifeq ($(GITHUB_ACTIONS_FORMATTING), 1)
55
else
66
FLAKE8_FORMAT=
77
endif
8+
.PHONY: test docs
89

9-
doc:
10-
@(cd docs/ && make html)
10+
docs:
11+
@(cd docs/ && (make html SPHINXOPTS="-W --keep-going -n"))
1112

1213
lint:
1314
@echo " Linting FUSE codebase"
@@ -36,4 +37,7 @@ test_cells:
3637
@firedrake-clean
3738
@python3 -m pytest -rPx --run-cleared test/test_cells.py::test_ref_els[expect1]
3839

39-
prepush: lint tests doc
40+
clean:
41+
@(cd docs/ && make clean)
42+
43+
prepush: lint tests clean docs

‎docs/Makefile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
# from the environment for the first two.
66
SPHINXOPTS ?=
77
SPHINXBUILD =python3 -m sphinx
8+
SPHINXAUTOBUILD ?= sphinx-autobuild
89
SOURCEDIR = source
910
BUILDDIR = build
1011

@@ -16,6 +17,10 @@ help:
1617

1718
autodoc:
1819
@sphinx-apidoc -o "$(SOURCEDIR)" "."
20+
21+
auto-%: Makefile
22+
@$(SPHINXAUTOBUILD) -M $* "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
23+
1924
# Catch-all target: route all unknown targets to Sphinx using the new
2025
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
2126
%: Makefile

‎docs/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Building
2+
========
3+
4+
To build the website locally, you need Sphinx and a couple of plugins:
5+
```console
6+
python -m pip install sphinx sphinx_bootstrap_theme sphinx_design
7+
```
8+
Then:
9+
```console
10+
make html
11+
```
12+
The resulting files will appear in `build/html`.
13+
14+
If you further install sphinx-autobuild:
15+
```console
16+
python -m pip install sphinx-autobuild
17+
```
18+
then you can start a local web server that automatically rebuilds when you save any source file with:
19+
```console
20+
make auto-html
21+
```
22+
Point your web browser at [http://127.0.0.1:8000/](http://127.0.0.1:8000/) to see the site.

‎docs/source/_static/additional.css‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
div.documentwrapper div.bodywrapper { margin-left: 350px;}
2+
div.document div.sphinxsidebar { width: 40px; }
3+
4+
div.sphinxsidebarwrapper div {
5+
overflow: auto;
6+
}
7+
8+
div.bs-sidenav div {
9+
overflow: auto;
10+
}
11+
12+
.bs-sidenav .nav > li > a {
13+
display: block;
14+
/* color: #716b7a; */
15+
color: #672cbf;
16+
padding: 5px 20px;
17+
}

‎docs/source/about.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
:orphan: true
2+
3+
.. title:: FUSE
4+
5+
FUSE: A finite, unifed, serialisable finite element.
6+
======================================================
7+
8+
FUSE is an implementation of a complete finite element definition.

‎docs/source/api.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
:tocdepth: 1
2+
3+
API documentation
4+
-------------------
5+
6+
.. toctree::
7+
:maxdepth: 1
8+
9+
api/groups
10+
api/cells
11+
api/spaces
12+
api/triples
13+
api/dof
14+
api/examples2d
15+
api/examples3d
16+
api/serialisation

‎docs/source/cells.rst‎ renamed to ‎docs/source/api/cells.rst‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
1+
:tocdepth: 0
2+
13
Cells
24
============
35

46

57
.. automodule:: fuse.cells
68
:members:
79
:exclude-members: Arrow3D
8-
:show-inheritance:
10+
:show-inheritance:
11+
:no-index:

‎docs/source/api/dof.rst‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
DOFs
2+
==============
3+
Each degree of freedom :math:`\mathcal{X}_i` can be represented in an integral form:
4+
5+
.. math::
6+
7+
\mathcal{X}_i (\vec{f}, g) = \langle \kappa(x, g), \vec{f}(x) \rangle_{\mathcal{V}, gE}
8+
9+
.. list-table:: Integral Form of a DOF
10+
:widths: 25 75
11+
:header-rows: 1
12+
13+
* - Symbol
14+
- Description
15+
* - :math:`E`
16+
- Entity the DOF is defined over
17+
* - :math:`\vec{f}``
18+
- Input function to the linear functional, in the space :math:`\mathcal{V}` on :math:`E`
19+
* - :math:`x`
20+
- Local coordinate vector on :math:`E`
21+
* - :math:`\mathcal{V}`
22+
- Space from the definition triple (:math:`\mathcal{C}`, :math:`\mathcal{V}`, :math:`\mathcal{E}`)
23+
* - :math:`g`
24+
- A member of :math:`\mathcal{G}_1` that will be varied to generate the DOFs.
25+
* - :math:`\kappa`
26+
- Kernel - the linear functional that transforms under the group action
27+
* - :math:`\langle \cdot, \cdot \rangle_{\mathcal{V}, E}`
28+
- A pairing over the entity that combines the kernel and the function.
29+
30+
The classes documented on this page provide options for the kernel :math:`\kappa` and the pairing :math:`\langle \cdot, \cdot \rangle_{\mathcal{V}, E}`.
31+
32+
.. automodule:: fuse.dof
33+
:members:
34+
:show-inheritance:

‎docs/source/examples.rst‎ renamed to ‎docs/source/api/examples2d.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ This page will describe the foundational element definitions and how they are wr
55

66
DG0
77
--------------------------
8-
.. literalinclude:: ../../test/test_2d_examples_docs.py
8+
.. literalinclude:: ../../../test/test_2d_examples_docs.py
99
:language: python3
1010
:dedent:
1111
:start-after: [test_dg0 0]
@@ -15,7 +15,7 @@ DG0
1515
DG1 on interval
1616
--------------------------
1717

18-
.. literalinclude:: ../../test/test_2d_examples_docs.py
18+
.. literalinclude:: ../../../test/test_2d_examples_docs.py
1919
:language: python3
2020
:dedent:
2121
:start-after: [test_dg1_int 0]
@@ -46,7 +46,7 @@ DG1 on interval
4646
4747
DG1 on triangle
4848
--------------------------
49-
.. literalinclude:: ../../test/test_2d_examples_docs.py
49+
.. literalinclude:: ../../../test/test_2d_examples_docs.py
5050
:language: python3
5151
:dedent:
5252
:start-after: [test_dg1_tri 0]
@@ -58,7 +58,7 @@ DG1 on triangle
5858
CG1 on interval
5959
--------------------------
6060

61-
.. literalinclude:: ../../test/test_2d_examples_docs.py
61+
.. literalinclude:: ../../../test/test_2d_examples_docs.py
6262
:language: python3
6363
:dedent:
6464
:start-after: [test_cg1 0]
@@ -70,7 +70,7 @@ CG1 on interval
7070
CG3 on triangle
7171
--------------------------
7272

73-
.. literalinclude:: ../../test/test_2d_examples_docs.py
73+
.. literalinclude:: ../../../test/test_2d_examples_docs.py
7474
:language: python3
7575
:dedent:
7676
:start-after: [test_cg3 0]

‎docs/source/api/examples3d.rst‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
Examples in 3D
2+
===========================
3+
4+
This page will describe the foundational element definitions in three dimensions and how they are written in this software.
5+
6+
Describing a tetrahedron
7+
--------------------------
8+
A tetrahedron is initially set up like this:
9+
10+
.. literalinclude:: ../../../test/test_3d_examples_docs.py
11+
:language: python3
12+
:dedent:
13+
:start-after: [make_tet 0]
14+
:end-before: [make_tet 1]
15+
16+
and then components of the tetrahedron may be extracted using either the helper functions Point.vertices and Point.edges or the generic function Point.d_entities.
17+
18+
.. literalinclude:: ../../../test/test_3d_examples_docs.py
19+
:language: python3
20+
:dedent:
21+
:start-after: [make_tet 1]
22+
:end-before: [make_tet 2]
23+
24+
CG3 on a tetrahedron
25+
--------------------------
26+
27+
.. literalinclude:: ../../../test/test_3d_examples_docs.py
28+
:language: python3
29+
:dedent:
30+
:start-after: [test_tet_cg3 0]
31+
:end-before: [test_tet_cg3 1]
32+
33+
Raviart Thomas on a tetrahedron
34+
------------------------------------
35+
36+
.. literalinclude:: ../../../test/test_3d_examples_docs.py
37+
:language: python3
38+
:dedent:
39+
:start-after: [test_tet_rt 0]
40+
:end-before: [test_tet_rt 1]
41+
42+
43+
Nedelec on a tetrahedron
44+
-----------------------------------
45+
46+
.. literalinclude:: ../../../test/test_3d_examples_docs.py
47+
:language: python3
48+
:dedent:
49+
:start-after: [test_tet_ned 0]
50+
:end-before: [test_tet_ned 1]

0 commit comments

Comments
 (0)