From 318c43d62df512c74d7453ea8d2a4b8aee21055b Mon Sep 17 00:00:00 2001
From: Forgejo Actions <forgejo-actions@localhost>
Date: Sun, 19 Apr 2026 00:50:22 -0700
Subject: [PATCH] [docs] high level doc updates

---
 README.md          | 49 ++++++----------------------------------------
 docs/index.md      | 24 ++++++++++++++---------
 meanas/__init__.py |  4 ++--
 3 files changed, 23 insertions(+), 54 deletions(-)

diff --git a/README.md b/README.md
index c6381e1..555f0cf 100644
--- a/README.md
+++ b/README.md
@@ -109,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.
@@ -121,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:
-
-1. Build an FDFD operator or waveguide port source, then solve a driven
-   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.
+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
+pages are there to document the mathematical conventions and derivations behind
+those tools.
 
 ## Documentation
 
@@ -135,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
@@ -184,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.
diff --git a/docs/index.md b/docs/index.md
index cc2d692..32c5644 100644
--- a/docs/index.md
+++ b/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
-  phasor extraction.
-- Use the [FDFD API](api/fdfd.md) when you need driven frequency-domain solves
-  or operator algebra.
-- Use the [Waveguide API](api/waveguides.md) for mode solving, port sources, and
-  overlap windows.
-- Use the [fdmath API](api/fdmath.md) when you need the lower-level finite-difference
-  operators or the derivation background shared across the package.
+For most users, the tracked examples under `examples/` are the right entry
+point. They show the intended combinations of tools for solving complete
+problems.
+
+The API pages are better read as a toolbox map and derivation reference:
+
+- Use the [FDTD API](api/fdtd.md) for time-domain stepping, CPML, and phasor
+  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
 
diff --git a/meanas/__init__.py b/meanas/__init__.py
index ef079fb..dcb925f 100644
--- a/meanas/__init__.py
+++ b/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
-