[docs] switch generated docs to MkDocs
This commit is contained in:
parent
5e95d66a7e
commit
a82eb5858a
54 changed files with 350 additions and 2000 deletions
4
.gitignore
vendored
4
.gitignore
vendored
|
|
@ -54,6 +54,10 @@ coverage.xml
|
|||
|
||||
# documentation
|
||||
doc/
|
||||
site/
|
||||
_doc_mathimg/
|
||||
doc.md
|
||||
doc.htex
|
||||
|
||||
# PyBuilder
|
||||
target/
|
||||
|
|
|
|||
27
README.md
27
README.md
|
|
@ -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
3
docs/api/eigensolvers.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# eigensolvers
|
||||
|
||||
::: meanas.eigensolvers
|
||||
15
docs/api/fdfd.md
Normal file
15
docs/api/fdfd.md
Normal 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
13
docs/api/fdmath.md
Normal 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
15
docs/api/fdtd.md
Normal 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
14
docs/api/index.md
Normal 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
3
docs/api/meanas.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# meanas
|
||||
|
||||
::: meanas
|
||||
7
docs/api/waveguides.md
Normal file
7
docs/api/waveguides.md
Normal 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
1
docs/assets/vendor/mathjax/core.js
vendored
Normal file
File diff suppressed because one or more lines are too long
1
docs/assets/vendor/mathjax/input/asciimath.js
vendored
Normal file
1
docs/assets/vendor/mathjax/input/asciimath.js
vendored
Normal file
File diff suppressed because one or more lines are too long
1
docs/assets/vendor/mathjax/input/mml.js
vendored
Normal file
1
docs/assets/vendor/mathjax/input/mml.js
vendored
Normal file
File diff suppressed because one or more lines are too long
1
docs/assets/vendor/mathjax/input/mml/entities.js
vendored
Normal file
1
docs/assets/vendor/mathjax/input/mml/entities.js
vendored
Normal file
File diff suppressed because one or more lines are too long
34
docs/assets/vendor/mathjax/input/tex-full.js
vendored
Normal file
34
docs/assets/vendor/mathjax/input/tex-full.js
vendored
Normal file
File diff suppressed because one or more lines are too long
1
docs/assets/vendor/mathjax/loader.js
vendored
Normal file
1
docs/assets/vendor/mathjax/loader.js
vendored
Normal file
File diff suppressed because one or more lines are too long
38
docs/assets/vendor/mathjax/manifest.json
vendored
Normal file
38
docs/assets/vendor/mathjax/manifest.json
vendored
Normal 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"
|
||||
}
|
||||
1
docs/assets/vendor/mathjax/output/chtml.js
vendored
Normal file
1
docs/assets/vendor/mathjax/output/chtml.js
vendored
Normal file
File diff suppressed because one or more lines are too long
1
docs/assets/vendor/mathjax/output/chtml/fonts/tex.js
vendored
Normal file
1
docs/assets/vendor/mathjax/output/chtml/fonts/tex.js
vendored
Normal file
File diff suppressed because one or more lines are too long
BIN
docs/assets/vendor/mathjax/output/chtml/fonts/woff-v2/MathJax_AMS-Regular.woff
vendored
Normal file
BIN
docs/assets/vendor/mathjax/output/chtml/fonts/woff-v2/MathJax_AMS-Regular.woff
vendored
Normal file
Binary file not shown.
BIN
docs/assets/vendor/mathjax/output/chtml/fonts/woff-v2/MathJax_Calligraphic-Bold.woff
vendored
Normal file
BIN
docs/assets/vendor/mathjax/output/chtml/fonts/woff-v2/MathJax_Calligraphic-Bold.woff
vendored
Normal file
Binary file not shown.
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue