Publish Full nml-tools Documentation On Read The Docs #58

Create a complete, versioned nml-tools documentation site and publish it on
Read the Docs. Move the detailed user guidance currently concentrated in the
README into a navigable documentation structure while keeping the README as a
concise project overview and quick start.

Use Sphinx with MyST Markdown support so existing Markdown material can be
reused, while retaining access to mature Python API documentation, Click CLI
documentation, cross-references, versioned builds, and static-file publishing.

The site should also publish the machine-readable nml-tools dialect meta-schema described in #57.
Complex type documentation is tracked in #56.

Motivation

nml-tools now covers substantially more than can be presented comfortably in a
single README:

• schema loading, references, and Fortran extensions;
• generated Fortran helper and namelist modules;
• defaults, requiredness, sentinels, validation, and runtime dimensions;
• intrinsic and derived arrays;
• local and imported derived types;
• templates and generated Markdown;
• file profiles and CLI workflows;
• f2py/Python wrappers; and
• a growing set of compatibility policies and feature boundaries.

A documentation site should make these features discoverable by task, provide
stable links for issue discussions and generated diagnostics, and host the
versioned nml-tools schema dialect.

Documentation Stack

Add a documentation-only dependency group containing at least:

• Sphinx;
• MyST Parser;
• a maintained responsive Sphinx theme
• sphinx-click for generated Click command reference; and
• any small supporting extension needed for copy buttons or external links.

Keep documentation dependencies out of the core runtime installation. Install
them through a docs optional dependency or a dedicated locked requirements
file consumed by both local builds and Read the Docs.

Add:

.readthedocs.yaml
docs/conf.py
docs/index.md
docs/_static/

Configure Read the Docs with its version 2 configuration format, Python 3.12,
and an editable installation of the package plus documentation dependencies.
Enable pull-request documentation previews.

The local build command should be simple and documented, for example:

python -m sphinx -W --keep-going -b html docs docs/_build/html

Information Architecture

Organize the initial site around user tasks rather than source modules.

Introduction

• Project overview and design goals.
• Supported Python and Fortran environments.
• Installation, including optional extras.
• A minimal schema-to-generated-Fortran quick start.
• Links to the issue tracker, repository, and release notes.

Tutorials

• Generate and read a first namelist module.
• Add defaults, required values, constraints, and templates.
• Configure constants and runtime dimensions.
• Reuse schemas with $defs and $ref.
• Define local and imported derived types.
• Generate and use f2py/Python wrappers.
• Validate single- and multi-group namelist files.

Base tutorials on committed examples so commands and generated output can be
tested rather than maintained as disconnected prose.

Schema Language Reference

• Root schema structure and x-fortran-namelist.
• Scalar types, including the future first-class complex type.
• Arrays, dimensions, element order, and flexible tails.
• Derived types and component-order contracts.
• Defaults, examples, requiredness, and presence semantics.
• Enums, numeric bounds, and string lengths/formats.
• $defs, local-file $ref, and use-site composition.
• Every supported x-fortran-* keyword.
• Unsupported JSON Schema features and targeted diagnostics.
• nml-tools dialect identity, versioning, and deviations from standard JSON
  Schema.

Configuration Reference

• Standalone nml-config.toml and [tool.nml-tools] layouts.
• required-version and legacy minimum-version.
• Helper, namelist, template, Markdown, and f2py output configuration.
• Constants, runtime dimensions, kinds, and file profiles.
• Path resolution and naming/collision rules.
• Complete annotated configuration examples.

CLI Reference

• Generate and check workflows.
• Individual generator commands.
• Namelist validation and schema-only validation.
• Constants and dimension overrides.
• Profiles, verbosity, exit statuses, and error behavior.
• Generated command signatures and options sourced from the Click command tree
  so they cannot silently drift from the implementation.

Generated Fortran API

• Generated types, storage, and initialization lifecycle.
• init, init_type, from_file, set, set_dims, is_set, is_valid, and
  filled_shape where applicable.
• Error codes and errmsg handling.
• Required/default/sentinel behavior.
• Runtime allocation and dimension-reset behavior.
• Native derived types and imported type contracts.
• Fortran compiler support and known processor differences.

Python And f2py API

• Build requirements and package integration.
• Opaque handles and object lifetime.
• Scalar, array, string, derived mapping, and future complex arguments.
• Runtime dimensions and validation.
• NumPy dtype/kind mappings.
• Generated Python shim behavior and exceptions.

Namelist Syntax And Validation

• Standard component and buffer-style assignment.
• Fortran array order and sections.
• Null values, repetition, and partial assignment.
• Derived component syntax.
• Current f90nml limitations and the schema-aware parser roadmap.
• Strict standard syntax versus documented compatibility extensions once the
  custom parser is available.

Examples And Explanations

• Render or link every maintained example project.
• Explain what each generated artifact is for.
• Include tested snippets rather than full duplicated generated files where
  possible.

Development And Contributing

• Editable installation and test commands.
• Ruff, mypy, coverage, and compiler-matrix checks.
• Generated-fixture update policy.
• Architecture overview by subsystem.
• Release and documentation contribution workflow.

README Migration

Keep the README useful on GitHub and PyPI, but reduce it to:

• one-paragraph project description;
• key features and current limitations;
• installation;
• one compact quick start;
• links to the full documentation, examples, and issue tracker; and
• build/status badges.

Move detailed schema, configuration, CLI, generated API, and compatibility
sections into the documentation site. Preserve useful anchors through redirect
notes or stable documentation links where practical.

Do not remove detailed README material until the corresponding documentation
page exists and the published links are working.

API And CLI Generation

Use Sphinx autodoc/autosummary for intentional public Python APIs. Keep private
implementation modules out of the primary API navigation unless an architecture
page explicitly discusses them.

Use sphinx-click or an equivalent deterministic integration to render CLI
commands from the actual Click command tree. Documentation builds must not
write generated source files or require Fortran compilers.

For generated Fortran APIs, maintain hand-authored conceptual documentation
backed by tested examples. Doxygen-oriented comments in generated source do not
replace the user guide.

Dialect And Static Schema Publishing

Publish the bundled meta-schema at a stable path under the documentation host,
for example:

https://nml-tools.readthedocs.io/en/latest/schema/v1/nml-tools.schema.json

Configure Sphinx to copy the canonical package resource into the HTML output
without maintaining a second editable copy. Add a human-readable schema dialect
landing page adjacent to the machine-readable resource.

The dialect path includes v1 and must remain immutable. Documentation pages
may evolve and clarify behavior without changing the meaning of the published
meta-schema.

Read The Docs Configuration

• Register the project under the nml-tools Read the Docs slug if available.
• Build the default branch as latest.
• Build release tags and expose the latest release as stable.
• Enable pull-request previews for documentation changes.
• Use Python 3.12 to match CI typing and test configuration.
• Install the project and documentation extra through the checked-in RTD
  configuration.
• Fail builds on Sphinx warnings.
• Keep external network requirements out of ordinary documentation rendering.
• Configure canonical URLs and a custom domain later without breaking the
  published dialect URI.

Search, Navigation, And Accessibility

• Provide a concise top-level navigation tree and local page tables of contents.
• Ensure schema keywords, CLI commands, generated methods, and error codes are
  searchable.
• Use semantic headings, accessible code-block labels, descriptive links, and
  sufficient color contrast.
• Keep examples readable on narrow screens.
• Avoid documenting behavior only through screenshots.

Tests And CI

Add documentation checks that:

• build HTML with warnings treated as errors;
• verify internal references and duplicate anchors;
• import the installed package when generating API and CLI reference;
• verify all included literal files and example paths exist;
• execute or reuse tests for tutorial commands and important snippets;
• verify the published meta-schema is copied to the expected output path;
• ensure the documentation meta-schema is byte-identical to the bundled package
  resource; and
• check external links in a separate scheduled or manually triggered job so
  transient network failures do not block every code change.

Add the documentation build to normal CI. Read the Docs remains the publishing
service, not the only place where documentation correctness is tested.

Rollout

1. Add the Sphinx/MyST project, RTD configuration, theme, and CI build.
2. Publish the existing README content with a clear navigation structure.
3. Fill documentation gaps for generated Fortran, f2py, references, derived
   types, validation, and file profiles.
4. Publish the nml-tools dialect meta-schema and dialect reference.
5. Shorten the README only after the equivalent pages are live.
6. Add optional SchemaStore registration after a stable URI and safe schema
   filename convention exist.

Acceptance Criteria

• nml-tools has a successful public Read the Docs project with latest and
  versioned release documentation.
• Documentation builds locally and in CI with warnings treated as errors.
• Installation, tutorials, schema reference, configuration, CLI, generated
  Fortran, and f2py/Python APIs are covered.
• CLI option documentation is derived from the Click implementation.
• Maintained examples back the tutorials.
• The nml-tools dialect meta-schema is available at its documented versioned
  URI and bundled offline with the package.
• The README becomes a concise entry point without losing information.
• Documentation preview builds are available for pull requests.
• Navigation, search, and mobile presentation are usable.

Out Of Scope

• Replacing generated per-project Markdown documentation.
• Hosting arbitrary user schemas or generated project documentation.
• Translating the documentation in the initial release.
• Requiring a Fortran compiler for ordinary documentation builds.
• SchemaStore registration before the dialect URI and filename policy are
  stable.