[docs] high level doc updates

README.md

@@ -56,6 +56,21 @@ 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]'
 ```
 
@@ -94,7 +109,7 @@ python3 -m pytest -rsxX | tee test_results.txt
 
 ## Use
 
-`meanas` is organized around a few core workflows:
+`meanas` is a collection of finite-difference electromagnetics tools:
 
 - `meanas.fdfd`: frequency-domain wave equations, sparse operators, SCPML, and
   iterative solves for driven problems.
@@ -106,13 +121,10 @@ 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.
 
-The most mature user-facing workflows are:
+For most users, the tracked examples under `examples/` are the right entry
-
+point. The library API is primarily a toolbox; the module docstrings and API
-1. Build an FDFD operator or waveguide port source, then solve a driven
+pages are there to document the mathematical conventions and derivations behind
-   frequency-domain problem.
+those tools.
-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
 
@@ -120,37 +132,6 @@ 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
@@ -169,13 +150,10 @@ 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.
 
-Tracked examples under `examples/` are the intended starting points:
+The tracked examples under `examples/` are the intended entry points for users:
 
 - `examples/fdtd.py`: broadband FDTD pulse excitation, phasor extraction, and a
   residual check against the matching FDFD operator.

docs/index.md

@@ -11,16 +11,22 @@ This documentation is built directly from the package docstrings. The API pages
 are the source of truth for the mathematical derivations and calling
 conventions.
 
-## Recommended starting points
+## Examples and API Map
 
-- Use the [FDTD API](api/fdtd.md) when you need time-domain stepping, CPML, or
+For most users, the tracked examples under `examples/` are the right entry
-  phasor extraction.
+point. They show the intended combinations of tools for solving complete
-- Use the [FDFD API](api/fdfd.md) when you need driven frequency-domain solves
+problems.
-  or operator algebra.
+
-- Use the [Waveguide API](api/waveguides.md) for mode solving, port sources, and
+The API pages are better read as a toolbox map and derivation reference:
-  overlap windows.
+
-- Use the [fdmath API](api/fdmath.md) when you need the lower-level finite-difference
+- Use the [FDTD API](api/fdtd.md) for time-domain stepping, CPML, and phasor
-  operators or the derivation background shared across the package.
+  extraction.
+- 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,7 +1,8 @@
 """
 Electromagnetic simulation tools
 
-See the readme or `import meanas; help(meanas)` for more info.
+See the tracked examples for end-to-end workflows, and `help(meanas)` for the
+toolbox overview and API derivations.
 """
 
 import pathlib
@@ -16,4 +17,3 @@ try:
         __doc__ = f.read()
 except Exception:
     pass
-

pyproject.toml

@@ -39,7 +39,7 @@ include = [
     ]
 dynamic = ["version"]
 dependencies = [
-    "gridlock",
+    "gridlock>=2.1",
     "numpy>=2.0",
     "scipy~=1.14",
 ]
@@ -50,14 +50,9 @@ path = "meanas/__init__.py"
 
 [project.optional-dependencies]
 dev = [
-    "pytest",
+    "meanas[test]",
-    "coverage",
+    "meanas[docs]",
-    "gridlock",
+    "meanas[examples]",
-    "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",
     ]
@@ -68,10 +63,8 @@ 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"]