[docs] switch generated docs to MkDocs

This commit is contained in:
Jan Petykiewicz 2026-04-18 15:05:35 -07:00
commit a82eb5858a
54 changed files with 350 additions and 2000 deletions

4
.gitignore vendored
View file

@ -54,6 +54,10 @@ coverage.xml
# documentation
doc/
site/
_doc_mathimg/
doc.md
doc.htex
# PyBuilder
target/

View file

@ -114,6 +114,33 @@ The most mature user-facing workflows are:
`meanas.fdtd.accumulate_phasor(...)`, and compare those phasors against an
FDFD reference on the same Yee grid.
## Documentation
API and workflow docs are generated from the package docstrings with
[MkDocs](https://www.mkdocs.org/), [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/),
and [mkdocstrings](https://mkdocstrings.github.io/).
Install the docs toolchain with:
```bash
pip3 install -e './meanas[docs]'
```
Then build the docs site with:
```bash
./make_docs.sh
```
This produces:
- a normal multi-page site under `site/`
- a combined printable single-page HTML site under `site/print_page/`
- an optional fully inlined `site/standalone.html` when `htmlark` is available
The docs build uses a local MathJax bundle vendored under `docs/assets/`, so
the rendered HTML does not rely on external services for equation rendering.
Tracked examples under `examples/` are the intended starting points:
- `examples/fdtd.py`: broadband FDTD pulse excitation, phasor extraction, and a

3
docs/api/eigensolvers.md Normal file
View file

@ -0,0 +1,3 @@
# eigensolvers
::: meanas.eigensolvers

15
docs/api/fdfd.md Normal file
View file

@ -0,0 +1,15 @@
# fdfd
::: meanas.fdfd
## Core operator layers
::: meanas.fdfd.functional
::: meanas.fdfd.operators
::: meanas.fdfd.solvers
::: meanas.fdfd.scpml
::: meanas.fdfd.farfield

13
docs/api/fdmath.md Normal file
View file

@ -0,0 +1,13 @@
# fdmath
::: meanas.fdmath
## Functional and sparse operators
::: meanas.fdmath.functional
::: meanas.fdmath.operators
::: meanas.fdmath.vectorization
::: meanas.fdmath.types

15
docs/api/fdtd.md Normal file
View file

@ -0,0 +1,15 @@
# fdtd
::: meanas.fdtd
## Core update and analysis helpers
::: meanas.fdtd.base
::: meanas.fdtd.pml
::: meanas.fdtd.boundaries
::: meanas.fdtd.energy
::: meanas.fdtd.phasor

14
docs/api/index.md Normal file
View file

@ -0,0 +1,14 @@
# API Overview
The package is documented directly from its docstrings. The most useful entry
points are:
- [meanas](meanas.md): top-level package overview
- [eigensolvers](eigensolvers.md): generic eigenvalue utilities used by the mode solvers
- [fdfd](fdfd.md): frequency-domain operators, sources, PML, solvers, and far-field transforms
- [waveguides](waveguides.md): straight, cylindrical, and 3D waveguide mode helpers
- [fdtd](fdtd.md): timestepping, CPML, energy/flux helpers, and phasor extraction
- [fdmath](fdmath.md): shared discrete operators, vectorization helpers, and derivation background
The waveguide and FDTD pages are the best places to start if you want the
mathematical derivations rather than just the callable reference.

3
docs/api/meanas.md Normal file
View file

@ -0,0 +1,3 @@
# meanas
::: meanas

7
docs/api/waveguides.md Normal file
View file

@ -0,0 +1,7 @@
# waveguides
::: meanas.fdfd.waveguide_2d
::: meanas.fdfd.waveguide_3d
::: meanas.fdfd.waveguide_cyl

1
docs/assets/vendor/mathjax/core.js vendored Normal file

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

1
docs/assets/vendor/mathjax/loader.js vendored Normal file

File diff suppressed because one or more lines are too long

View file

@ -0,0 +1,38 @@
{
"etag": "7ab8013dfc2c395304109fe189c1772ef87b366a",
"files": {
"core.js": 212262,
"loader.js": 16370,
"startup.js": 22870,
"input/tex-full.js": 270711,
"input/asciimath.js": 107690,
"input/mml.js": 13601,
"input/mml/entities.js": 32232,
"output/chtml.js": 211041,
"output/chtml/fonts/tex.js": 104359,
"output/chtml/fonts/woff-v2/MathJax_Zero.woff": 1368,
"output/chtml/fonts/woff-v2/MathJax_Vector-Regular.woff": 1136,
"output/chtml/fonts/woff-v2/MathJax_Vector-Bold.woff": 1116,
"output/chtml/fonts/woff-v2/MathJax_Typewriter-Regular.woff": 17604,
"output/chtml/fonts/woff-v2/MathJax_Size4-Regular.woff": 5148,
"output/chtml/fonts/woff-v2/MathJax_Size3-Regular.woff": 3244,
"output/chtml/fonts/woff-v2/MathJax_Size2-Regular.woff": 5464,
"output/chtml/fonts/woff-v2/MathJax_Size1-Regular.woff": 5792,
"output/chtml/fonts/woff-v2/MathJax_Script-Regular.woff": 11852,
"output/chtml/fonts/woff-v2/MathJax_SansSerif-Regular.woff": 12660,
"output/chtml/fonts/woff-v2/MathJax_SansSerif-Italic.woff": 14628,
"output/chtml/fonts/woff-v2/MathJax_SansSerif-Bold.woff": 15944,
"output/chtml/fonts/woff-v2/MathJax_Math-Regular.woff": 19288,
"output/chtml/fonts/woff-v2/MathJax_Math-Italic.woff": 19360,
"output/chtml/fonts/woff-v2/MathJax_Math-BoldItalic.woff": 19776,
"output/chtml/fonts/woff-v2/MathJax_Main-Regular.woff": 34160,
"output/chtml/fonts/woff-v2/MathJax_Main-Italic.woff": 20832,
"output/chtml/fonts/woff-v2/MathJax_Main-Bold.woff": 34464,
"output/chtml/fonts/woff-v2/MathJax_Fraktur-Regular.woff": 21480,
"output/chtml/fonts/woff-v2/MathJax_Fraktur-Bold.woff": 22340,
"output/chtml/fonts/woff-v2/MathJax_Calligraphic-Regular.woff": 9600,
"output/chtml/fonts/woff-v2/MathJax_Calligraphic-Bold.woff": 9908,
"output/chtml/fonts/woff-v2/MathJax_AMS-Regular.woff": 40808
},
"version": "3.1.4"
}

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

Some files were not shown because too many files have changed in this diff Show more