README.md

@@ -56,21 +56,6 @@ linear systems, ideally with double precision.
 
 Install from PyPI with pip:
 ```bash
-pip3 install meanas
-```
-
-Optional extras:
-
-- `meanas[test]`: pytest and coverage
-- `meanas[docs]`: MkDocs-based documentation toolchain
-- `meanas[examples]`: optional runtime dependencies used by the tracked examples
-- `meanas[dev]`: the union of `test`, `docs`, and `examples`, plus local lint/docs-publish helpers
-
-Examples:
-```bash
-pip3 install 'meanas[test]'
-pip3 install 'meanas[docs]'
-pip3 install 'meanas[examples]'
 pip3 install 'meanas[dev]'
 ```
 
@@ -109,7 +94,7 @@ python3 -m pytest -rsxX | tee test_results.txt
 
 ## Use
 
-`meanas` is a collection of finite-difference electromagnetics tools:
+`meanas` is organized around a few core workflows:
 
 - `meanas.fdfd`: frequency-domain wave equations, sparse operators, SCPML, and
   iterative solves for driven problems.
@@ -121,10 +106,13 @@ python3 -m pytest -rsxX | tee test_results.txt
 - `meanas.fdmath`: low-level finite-difference operators, vectorization helpers,
   and derivations shared by the FDTD and FDFD layers.
 
-For most users, the tracked examples under `examples/` are the right entry
+The most mature user-facing workflows are:
-point. The library API is primarily a toolbox; the module docstrings and API
+
-pages are there to document the mathematical conventions and derivations behind
+1. Build an FDFD operator or waveguide port source, then solve a driven
-those tools.
+   frequency-domain problem.
+2. Run an FDTD simulation, extract one or more frequency-domain phasors with
+   `meanas.fdtd.accumulate_phasor(...)`, and compare those phasors against an
+   FDFD reference on the same Yee grid.
 
 ## Documentation
 
@@ -132,6 +120,37 @@ 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/).
 
+When hosted on a Forgejo instance, the intended setup is:
+
+- publish the generated site from a dedicated `docs-site` branch
+- serve that branch from the instance's static-pages host
+- point the repository's **Wiki** tab at the published docs URL
+
+This repository now uses a version-controlled wrapper script rather than a
+Forgejo runner. After a successful `git push`, the wrapper builds the docs
+locally and force-updates the `docs-site` branch from the same machine.
+
+Use the wrapper instead of `git push` when publishing from your development
+machine:
+
+```bash
+./scripts/push_with_docs.sh
+```
+
+It only auto-publishes after successful pushes of local `master` to `origin`.
+For unusual refspecs or other remotes, push manually and publish the docs
+branch separately if needed.
+
+To persist the published docs URL for canonical MkDocs links in this clone, set
+the local git config value with:
+
+```bash
+./scripts/configure_docs_url.sh 'https://docs.example.com/meanas/'
+```
+
+The wrapper will also respect a shell-level `DOCS_SITE_URL` override if one is
+set.
+
 Install the docs toolchain with:
 
 ```bash
@@ -150,10 +169,13 @@ This produces:
 - a combined printable single-page HTML site under `site/print_page/`
 - an optional fully inlined `site/standalone.html` when `htmlark` is available
 
+The version-controlled push wrapper publishes this same output to the
+`docs-site` branch.
+
 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.
 
-The tracked examples under `examples/` are the intended entry points for users:
+Tracked examples under `examples/` are the intended starting points:
 
 - `examples/fdtd.py`: broadband FDTD pulse excitation, phasor extraction, and a
   residual check against the matching FDFD operator.

docs/index.md

@@ -11,22 +11,16 @@ This documentation is built directly from the package docstrings. The API pages
 are the source of truth for the mathematical derivations and calling
 conventions.
 
-## Examples and API Map
+## Recommended starting points
 
-For most users, the tracked examples under `examples/` are the right entry
+- Use the [FDTD API](api/fdtd.md) when you need time-domain stepping, CPML, or
-point. They show the intended combinations of tools for solving complete
+  phasor extraction.
-problems.
+- Use the [FDFD API](api/fdfd.md) when you need driven frequency-domain solves
-
+  or operator algebra.
-The API pages are better read as a toolbox map and derivation reference:
+- Use the [Waveguide API](api/waveguides.md) for mode solving, port sources, and
-
+  overlap windows.
-- Use the [FDTD API](api/fdtd.md) for time-domain stepping, CPML, and phasor
+- Use the [fdmath API](api/fdmath.md) when you need the lower-level finite-difference
-  extraction.
+  operators or the derivation background shared across the package.
-- Use the [FDFD API](api/fdfd.md) for driven frequency-domain solves and sparse
-  operator algebra.
-- Use the [Waveguide API](api/waveguides.md) for mode solving, port sources,
-  and overlap windows.
-- Use the [fdmath API](api/fdmath.md) for the lower-level finite-difference
-  operators and the shared discrete derivations underneath both solvers.
 
 ## Build outputs
 

meanas/__init__.py

@@ -1,8 +1,7 @@
 """
 Electromagnetic simulation tools
 
-See the tracked examples for end-to-end workflows, and `help(meanas)` for the
+See the readme or `import meanas; help(meanas)` for more info.
-toolbox overview and API derivations.
 """
 
 import pathlib
@@ -17,3 +16,4 @@ try:
         __doc__ = f.read()
 except Exception:
     pass
+

pyproject.toml

@@ -39,7 +39,7 @@ include = [
     ]
 dynamic = ["version"]
 dependencies = [
-    "gridlock>=2.1",
+    "gridlock",
     "numpy>=2.0",
     "scipy~=1.14",
 ]
@@ -50,9 +50,14 @@ path = "meanas/__init__.py"
 
 [project.optional-dependencies]
 dev = [
-    "meanas[test]",
+    "pytest",
-    "meanas[docs]",
+    "coverage",
-    "meanas[examples]",
+    "gridlock",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.25",
+    "mkdocs-print-site-plugin>=2.3",
+    "pymdown-extensions>=10.7",
     "htmlark>=1.0",
     "ruff>=0.6",
     ]
@@ -63,8 +68,10 @@ docs = [
     "mkdocs-print-site-plugin>=2.3",
     "pymdown-extensions>=10.7",
     "htmlark>=1.0",
+    "ruff>=0.6",
     ]
 examples = [
+    "gridlock>=2.1",
     "matplotlib>=3.10.8",
 ]
 test = ["pytest", "coverage"]