Developer documentation
=======================

.. note::

    **Internal scope.**  This section is the developer / contributor
    handbook for ``femorph-solver``.  The intended audience is people
    *building* the solver — authoring kernels, adding interop cards,
    extending the verification corpus, profiling performance.  An
    end-user reading the regular user guide should not need to open
    these pages.

    A future build step will hide this section from the public docs
    deployment (the section is currently published; planned to gate
    behind the ``FEMORPH_DEV_DOCS`` build flag — tracked separately).

The user-facing documentation lives under
:doc:`/getting-started/index`, :doc:`/user-guide/index`, and
:doc:`/reference/index`; this section is for the people landing the
code.

Best-practice handbook
----------------------

The pages below are the canonical "how we do it here" rules.  Each is
written so a new contributor can read it once and start authoring code
that matches the rest of the corpus.

.. toctree::
    :maxdepth: 1
    :caption: Documentation craft

    doc-style-guide
    ci-gates

.. toctree::
    :maxdepth: 1
    :caption: Architecture

    architecture

.. toctree::
    :maxdepth: 1
    :caption: Verification corpus

    verification_manual_spec
    verification_methodology
    fixtures_and_decks
    validation_data_store

.. toctree::
    :maxdepth: 1
    :caption: Tests + provenance

    testing
    provenance
    citing

.. toctree::
    :maxdepth: 1
    :caption: Reader + kernel authoring

    interop_authoring
    kernel_authoring
    solver_authoring

.. toctree::
    :maxdepth: 1
    :caption: Operations

    performance
    ci_and_merge
    release_process

What's here, what's coming
--------------------------

Already documented:

* :doc:`doc-style-guide` — single source of truth for docstring,
  RST, and tutorial style.  Read before writing or editing any
  user-facing prose.
* :doc:`ci-gates` — the docs CI gates (numpydoc per-symbol,
  doctest, linkcheck) and the rules they enforce.
* :doc:`architecture` — design principles, the layer-by-layer
  structure, why pyvista / scipy.sparse / pluggable solvers, and
  where to look when something's wrong.
* :doc:`verification_manual_spec` — how to add a Verification Manual
  example to the corpus.  Single source of truth for the spec types,
  the fixture / registry / harness layout, the multi-formulation
  pattern, and the reader-pending fallback.
* :doc:`verification_methodology` — the philosophy of resolving
  discrepancies once a benchmark fails.  Walk-through of branches
  (a) deck mis-author, (b) reader gap, (c) tolerance mis-set,
  (d) kernel / analysis-feature gap.
* :doc:`fixtures_and_decks` — the immutable-input-deck rule, vendor
  provenance preservation, when to re-author vs. when to vendor
  a vendor-shipped deck, common pitfalls.
* :doc:`validation_data_store` — architecture + rationale for the
  Cloudflare R2 store that holds vendor-solver output binaries
  (``.rst`` / ``.full`` / ``.emat`` / ``.mode``) outside the main
  repo.  Operational rules in the ``validation-data`` Claude skill.
* :doc:`testing` — test-suite layout, the four test categories,
  fixture conventions, parametrisation patterns, what to assert
  and what not to, pre-commit + CI overview.
* :doc:`provenance` — running inventory of every published reference
  cited by the source.  Each non-trivial numerical kernel must trace
  to a paper / textbook / public report.
* :doc:`interop_authoring` — adding a new card to ``from_bdf`` /
  ``from_inp`` / ``from_dat``: parser hooks, materialisation
  contract (real constants, materials, BCs, loads), unit-test
  pattern, coordinated card+kernel landings, common pitfalls.
* :doc:`kernel_authoring` — adding a new element kernel: the
  ``ElementBase`` contract, neutral-name convention, real-constant
  layout, DOF ordering, six-step walkthrough, patterns by element
  family, common pitfalls.
* :doc:`solver_authoring` — adding a new linear or eigen backend:
  the pluggable solver protocols, dispatch rules,
  shift-invert path, lazy-import discipline, common pitfalls.
* :doc:`performance` — profiling tooling, the two benchmark
  harnesses (micro / pipeline), when to commit a snapshot, how
  ``PERFORMANCE.md`` works, the release-readiness gate.
* :doc:`ci_and_merge` — the eight CI workflows, the label-driven
  merge queue (``automerge`` opt-in, rebase + serial-merge
  passes), the active-PR cap, pre-commit hooks, failure tracking.
* :doc:`release_process` — version bumps via ``setuptools-scm``,
  changelog conventions, the ``sphinx-multiversion`` story for
  old-tag galleries, yanking, the release-readiness gate.

The dev-handbook backlog is now empty; new pages get added when
a recurring review comment surfaces (write the rule once in a
page, link it from review, never write it again).

If you find yourself writing the same review comment more than once,
that comment belongs as a section in one of the pages above.  Open
a docs PR.

Companion non-docs files
------------------------

Some developer material lives outside the Sphinx tree because it is
heavily updated, machine-readable, or both.  Keep it cross-referenced
from the pages above, not duplicated here:

* ``SOURCES.md`` (repo root) — third-party sourcing policy.
* ``PERFORMANCE.md`` (repo root) — running performance tracker.
* ``tests/cross_solver/_verification_registry.py`` — the live VM
  registry; pages here describe its conventions but do not enumerate
  the rows.
* ``mpdl/docs/cyclic_expansion/`` — cyclic-symmetry expansion notes.
* ``perf/`` (repo root) — perf snapshots / trends / latest runs.