Proposal: a documentation readability pass for Hesiod

[barrulus]

Hi Otto - as promised, here's my proposed plan for the documentation work,
laid out for you to agree / comment / push back on before I start opening the
content PRs. I know you've also started deconstructing the docs yourself, so a
big goal here is to not step on your work — please tell me where our efforts
overlap and how you'd like to divide things.

Quick status of what's already in flight:

• Flatten export: fix blank output, add aspect-ratio control, guard bad output path #605 (flatten export) — merged, thanks for reconciling it onto the
  FlattenConfig rename.
• docs: wire User Manual & FAQ into nav; add "patch of graphs" guide #607 (docs nav + "patch of graphs" guide) — open against dev, rebased
  and building clean. It's the first concrete piece of what's below.

Everything from here targets dev.

---

What I found

I went through the published docs (https://hesioddoc.readthedocs.io) and the
docs/ tree. The bones are good — the per-node reference is genuinely useful.
The main gaps are structural and presentational:

1. The manual wasn't reachable. The User Manual and FAQ pages existed under
   docs/ but weren't in mkdocs.yml's nav:, so they never showed in the RTD
   sidebar. (Fixed in docs: wire User Manual & FAQ into nav; add "patch of graphs" guide #607, which also removes a broken duplicate page.)
2. No on-ramp. There's no "build your first terrain" tutorial; a newcomer
   lands on a 295-item node list with no guided path.
3. The node reference is example-poor. ~81% of node pages still say "No
   example available." The tooling to fix this already exists
   (scripts/update_doc.sh renders examples from .hsd files) — it's mostly
   missing example files.
4. The theme blocks readability. The current vendored classic MkDocs theme
   can't render admonitions — the > [!WARNING] block on the home page shows as
   broken-looking literal text on the live site, and we can't use note/tip/
   warning callouts anywhere.
5. Pages are islands. Manual pages don't cross-link to each other or to the
   node reference.

Proposed direction

A theme-first foundation, then content, shipped as small reviewable PRs.

Step 0 — Switch to Material for MkDocs (the one I'd like your call on first)

Migrate the docs to Material for MkDocs. It gives us admonitions, content
tabs, instant search, a dark-mode toggle, and auto-generated section nav — a
site-wide readability win and a much nicer base to write new content on. RTD
supports it via a small docs/requirements.txt + .readthedocs.yaml change.
I'd retire the vendored docs/custom-theme/ and keep the favicon.

This PR would be presentation only — no content rewrites — so the visual
change is easy to review in isolation. I'd pick sensible palette defaults that
echo Hesiod's dark UI; entirely yours to tweak.

This is the key decision. If you're happy with the Material direction, I'll
open that PR first; the rest builds on it.

Then, content (separate PRs, in roughly this order)

1. Core Concepts — the data model (heightmap / virtual array), masks &
   selectors, Broadcast/Receive routing, tiling & overlap, and a glossary. This
   is the vocabulary everything else links back to.
2. Getting Started — a generic end-to-end first terrain (noise → erosion →
   colorize → export), with screenshots. I'll capture the screenshots and verify
   the exact node-by-node steps myself so nothing is invented.
3. Topic guides — erosion (thermal vs hydraulic), masks/selectors,
   texturing, export formats, batch/headless mode.
4. Example backfill — add .hsd example files for common nodes so
   update_doc.sh lights up the "No example available" pages.
5. Cross-linking pass — wire the manual and node reference together.

Audience-wise I'd aim for a generic terrain/gamedev on-ramp as the main path,
with worldbuilding (the equirectangular / "patch of graphs" workflow) as an
advanced track.

How I'd like to work with you

• Everything off dev, small PRs, each with a human sponsor — easy to review or
  reject piece by piece.
• Since you're restructuring too: if any of the above clashes with what you've
  started, say so and I'll re-scope around it. Happy to take the pieces you'd
  rather hand off and leave the rest to you.

What I'm asking

1. Are you good with the Material for MkDocs migration as the foundation?
2. Does the content roadmap and ordering look right to you?
3. Where does this overlap with your own doc work, and how do you want to split
   it?

[otto-link]

Thanks a lot for this analysis and for the work plan. I fully align with what you proposed and you're welcome to start working on it.

I'll stay away from the documentation while you're working on it.

Two points of attention:

• Keep in mind that the application is evolving a lot (especially the nodes) so automatisation needs to be used whenever possible, see the scripts/update_doc.sh that writes a big part of the doc.
• the scripts/update_doc.sh is partially broken so some part of the doc may not update properly. I need to re-check/clean this.

Let me know if you need any help.

[barrulus]

ok excelleent. I will start with =aligning the update_doc.sh script to the new template, find the things that are best suited to automation and establish a pattern for that. We can incorporate that into CI so any doc affecting changes are inlined on any push.

[otto-link]

for the CI, that's a good idea. there is one difficulty though, some snapshots of the doc are generated using Hesiod executable (requires a GPU) and I'm not sure one can execute it on the Github CI

[barrulus]

I have seen that. They definitely cannot be generated using the Github CI, but it can be done as a pre-commit hook in instances where document changes are needed (on local). I am not going to enable it that way just yet, we may need to rely on a scheduled manual trigger for now as there is a lot to do :)

[otto-link]

yes, keep it simple for the first round, we could optimize later

[otto-link]

Side question, do you want me to integrate #607 right now?

[barrulus]

yes please :)

[otto-link]

I'll add here some complementary information for further integration

on tiling, overlap etc...:

• tiling
  • heightmaps are tiled primarily to distribute computation across CPU cores. Tiling can also reduce memory usage when working with very large maps. For GPU-based nodes, the solver generally falls back to a single large array internally, as this is typically more efficient than processing multiple tiles.
  • how to choose size, tiling, and overlap
    • when using the GUI
      • The maximum resolution is limited to 4k by default, as larger sizes become difficult to work with on typical hardware.
      • Use approximately as many tiles as CPU cores to maximize parallel computation.
      • Keep a relatively large overlap (0.5) to minimize numerical artifacts at tile boundaries.
    • When baking/exporting
      • The maximum resolution is limited to 32k (an arbitrary but practical limit).
      • Prefer a single tile (1 × 1) whenever possible to obtain the highest-quality results. This is usually slower but avoids tile boundary effects.
• advanced: storage modes
  • Virtual arrays (heightmaps) support several storage modes:
    • VA_RAM: all the heightmaps are persistent in RAM. Not exposed in Hesiod.
    • VA_DISK_LRU: Hybrid RAM/disk storage with a Least Recently Used cache. This is the default mode and keeps in memory only the virtual arrays being computed.
    • VA_DISK_LRU_MIN: Same mechanism, but keeps in memory only 2 tiles of the virtual arrays being computed. Slower, but significantly reduces memory usage and enables processing much larger maps. Available through the Trim Storage option in the graph configuration.
  • large graphs: for very large graphs, whether working in the GUI or during baking, enabling Trim Storage is generally recommended to reduce memory consumption.

on data types:

• Array: Lightweight 2D grid of scalar values, typically used for small kernels, filters, patterns, and localized operations. Common uses include custom convolutions, pattern stamping, and specialized nodes such as Expand/Shrink.
• Cloud: Collection of points in normalized space ([0,1] × [0,1]). Each point carries an associated scalar value that can be freely interpreted by the user: elevation, size, weight, density. Useful for object placement, points of interest, vegetation, props, and other sparse spatial data.
• Path: Ordered sequence of connected points in normalized space ([0,1] × [0,1]), optionally forming a closed loop. Each point carries an associated scalar value. Suitable for representing rivers, roads, ridges, contours, and other linear terrain features. Paths can be modified, enriched, and converted into heightmaps through dedicated nodes.
• VirtualArray: already in the new doc
• VirtualTexture: Reference to texture data containing four channels (RGBA: Red, Green, Blue, Alpha). Used to store and transfer color and transparency information between nodes.

[barrulus]

Just tiding up as this work has all been done, co,pleted and merged :)