Maintaining the Documentation¶

Zensical is an optional docs dependency group, not an application dependency or an MCP extra. From the repository root:

uv run --locked --group docs python scripts/docs.py build
uv run --locked --group docs python scripts/docs.py serve --port 8000

The preview binds to 127.0.0.1 only. Choose another port if 8000 is occupied. Preparation runs once at startup; restart the preview after editing the GUIDE, project records or authored docs/ sources to regenerate the topic pages. The build performs a clean strict Zensical build, then checks local HTML links, anchors, images and assets. python scripts/docs.py check repeats that check without rebuilding. prepare only regenerates the documentation input tree. No Qt, PyNite, server or application module is imported by the docs tooling. CI uses --only-group docs so it need not install the desktop/scientific stack.

The GUIDE remains the maintained detailed reference. scripts/docs.py maps every GUIDE heading into a topic page and copies the roadmaps, changelog and release record, rewriting repository-document links. Unmapped or duplicate headings and navigation omissions fail preparation. docs/ contains authored entry pages, the first-model tutorial, feature index, custom styles and screenshot assets. Add or update detailed workflows here in GUIDE.md, not in generated topic files. Update the topic map and zensical.toml navigation if you add a heading. Keep the feature index and tutorial accurate when workflows change. This avoids two competing copies of the manual.

Generated Markdown/assets live under .docs-build/docs; built HTML lives under site. Both are ignored. The existing logo and screenshots are copied from assets/; current workflow screenshots live in docs/assets/screenshots/ and are copied with the authored pages. GUIDE image links use docs/assets/... so they resolve in the repository; generation rebases them for each site topic. Search and light/dark appearance are provided by Zensical; system fonts avoid runtime Google Fonts requests. The documentation describes the current checkout and explicitly distinguishes experimental surface geometry/coupled slabs from established frame and separate plate-only workflows.

Refresh the native screenshots from the desktop development environment with python -B scripts/capture_docs.py (or use --output for a review directory). The script captures real widgets with temporary example files and settings, including a genuine topology finding and solved P-Delta result. It does not open web links or use personal project history. It defaults to Qt's offscreen platform; platform fonts can change the resulting pixels. Inspect every image before committing it. The three-storey image comes from the real offline 3D viewport check: run node tests/mesh_viewport.spec.cjs with Playwright configured, then copy /tmp/pynite-mesh-qa/multistorey.png to docs/assets/screenshots/three-storey-slabs.png. See the mesh viewport QA setup above. Capturing images requires the desktop/viewport dependencies; building the manual still requires only the docs dependency group. The 3D readability screenshot comes from node tests/viewport3d.spec.cjs: copy /tmp/pynite-3d-qa/desktop-diagram-readability.png to docs/assets/screenshots/spatial-diagram-readability.png after inspecting it.

.github/workflows/docs.yml builds/checks pull requests, uploads the generated site and deploys only trusted pushes to master or manual runs on that branch. It does not publish Python packages or alter release tags. To enable the planned site at https://praksharma.github.io/PyniteGUI/, the repository owner must select Settings > Pages > Build and deployment > Source: GitHub Actions, then push the documentation commit or run the Documentation workflow on master. The website URL is a deployment target, not a claim that the site is already live.

For standalone documentation tests:

uv run --locked --group docs python -B -m unittest discover -s tests -p 'test_docs.py'

Optional desktop browser QA: after building, run node tests/docs_site.spec.cjs with Playwright/Chromium installed separately (or set PLAYWRIGHT_MODULE as in the viewport checks). It serves site/ under the existing GitHub Pages /PyniteGUI/ prefix and checks images, search navigation, dark mode, key topics and desktop overflow. It closes its temporary server/browser and writes screenshots to /tmp/pynite-docs-qa (override with DOCS_QA_OUTPUT).

Source: GUIDE.md. This manual follows the current repository; the published rc1 wheel has a smaller feature set.