Update documentation contributor guide

docs/README.md

@@ -1,2 +1,111 @@
-# PyUnitWizard's Documentation
+# PyUnitWizard Documentation Guide
 
+This guide explains how the documentation project is organized and how to work with it day-to-day—from setting up the environment to publishing updates on GitHub Pages.
+
+## Directory Layout
+
+```
+docs/
+├── AGENTS.md                # Documentation-specific contribution rules
+├── README.md                # This contributor quick-start
+├── Makefile / make.bat      # Convenience wrappers for sphinx-build
+├── clean_api.py             # Removes stale autosummary outputs
+├── execute_notebooks.py     # Batch-executes notebooks & updates markers
+├── content/                 # Narrative guides and tutorials (MyST + notebooks)
+├── api/                     # Landing pages for API autosummary stubs
+├── _static/                 # Custom CSS/JS and other static assets
+├── _templates/              # Jinja templates consumed by Sphinx
+├── bibliography.bib         # Shared citation database
+└── ...
+```
+
+Notebooks typically live under `content/` and are tracked together with their `.nbconvert.last_run` timestamp files. Anything generated during builds—such as `_build/` or autosummary folders—is temporary and must be recreated locally when needed.
+
+## Environment Setup
+
+The documentation toolchain is defined in `devtools/conda-envs/docs_env.yaml`. Create (or update) the environment before running any docs-specific tasks:
+
+```bash
+conda env create -f devtools/conda-envs/docs_env.yaml  # first-time setup
+conda env update -f devtools/conda-envs/docs_env.yaml  # subsequent syncs
+conda activate pyunitwizard-docs
+```
+
+> ℹ️  If you already have the environment, `conda env update` is sufficient to pick up new dependencies.
+
+## Notebook Execution Workflow
+
+Use `docs/execute_notebooks.py` to execute notebooks and refresh `.nbconvert.last_run` markers:
+
+```bash
+# Run all notebooks below docs/content/
+python docs/execute_notebooks.py -r docs/content
+
+# Force execution even when timestamps are current
+python docs/execute_notebooks.py -r docs/content --force
+```
+
+After every run:
+
+1. Inspect `.nbconvert.log` files for errors. Fix issues and rerun as needed.
+2. Remove `.nbconvert.log` files before committing—they are build artifacts.
+3. Stage updated notebooks **together with** their `.nbconvert.last_run` companions so CI can skip unchanged notebooks.
+
+## Cleaning Autosummary Output
+
+Whenever the public API changes, clear obsolete autosummary trees to avoid stale reference pages:
+
+```bash
+python docs/clean_api.py
+```
+
+Run the command after a docs build that touches API pages, or before committing when you notice outdated files under `docs/api/autosummary/`.
+
+## Building the Docs Locally
+
+Sphinx builds can be triggered with the provided Makefile or directly via `sphinx-build`.
+
+```bash
+# Recommended: uses configuration from docs/Makefile
+(cd docs && make html)
+
+# Equivalent explicit invocation
+sphinx-build -M html docs docs/_build
+```
+
+Common targets include:
+
+- `make clean` – remove the `_build/` tree before a fresh build.
+- `make html` – render the full site for local preview.
+
+Open `docs/_build/html/index.html` in your browser to inspect the result. Never commit the `_build/` directory.
+
+## Publishing to GitHub Pages
+
+Documentation is published from the HTML output in `docs/_build/html`. The default workflow relies on GitHub Actions (`.github/workflows/sphinx_docs_to_gh_pages.yaml`), which automatically builds and deploys the site whenever the main branch is updated. Manual publishing is rarely needed, but when required:
+
+1. Build the site locally (`make html`).
+2. Push the rendered site to the `gh-pages` branch, for example:
+   ```bash
+   git subtree push --prefix docs/_build/html origin gh-pages
+   ```
+   Ensure the CI workflow is disabled or coordinated with maintainers before manual pushes.
+
+## Version Control Expectations
+
+- Track `.nbconvert.last_run` marker files alongside their notebooks.
+- Exclude `_build/`, `.nbconvert.log`, and other transient outputs from commits.
+- Regenerate autosummary content instead of hand-editing generated files.
+
+## Pre-PR Checklist
+
+Before opening a documentation pull request, confirm that you have:
+
+- [ ] Rebuilt the docs locally (`make html`) and resolved warnings.
+- [ ] Executed each modified notebook with `python docs/execute_notebooks.py` and cleaned up `.nbconvert.log` files.
+- [ ] Staged updated notebooks together with their `.nbconvert.last_run` markers.
+- [ ] Ensured `_build/` and other generated artifacts remain untracked.
+- [ ] Updated navigation, toctrees, or cross-references affected by your changes.
+- [ ] Documented any new dependencies or Sphinx extensions in the PR description.
+
+Following these steps keeps the documentation consistent and the CI pipeline green for every contributor.