Complete documentation and packaging housekeeping

[sergioald]

Summary

Completes the final documentation and packaging housekeeping pass for the current LDSFL-Meander maintenance sequence.

Documentation

• adds docs/index.md as a grouped entry point for user, validation, and maintainer documentation;
• repairs the malformed literal newline text at the end of README.md;
• reorganises the README documentation links;
• documents the user-configurable bank-erodibility / erosion-rate control;
• clarifies the adaptive-timestep interpretation of erosion rate;
• records the current resonance diagnostics and periodic-flow validation status;
• removes the stale hard-coded pytest count from the project-health checklist;
• updates the v0.6.5 release-notes draft with the completed maintenance work;
• updates the short user manual with erosion-rate and resonance guidance.

Packaging and metadata

• adds project, issue, documentation, and DOI URLs to pyproject.toml;
• adds build and twine to the development dependencies;
• enriches CITATION.cff with given names, repository metadata, and the Zenodo concept DOI;
• adds MANIFEST.in so source distributions retain the citation, manuals, example inputs, and research-software documentation;
• adds a Python 3.12 CI packaging check that builds the sdist and wheel, validates metadata with Twine, installs the wheel, and checks the ldsfl-run entry point;
• uploads the built distributions as a CI artifact.

Regression coverage

Adds tests/test_project_metadata.py to verify:

• version consistency between pyproject.toml, ldsfl.__version__, CITATION.cff, and the README badge;
• absence of the previous literal newline artefact;
• existence of local links in the README and documentation index;
• repository and DOI citation metadata;
• required source-distribution manifest entries.

Why

The numerical and user-interface maintenance work is now complete, but the repository still had several housekeeping gaps:

• documentation was spread across many files without a central index;
• the README ended with malformed escaped newline text;
• project-health guidance contained an obsolete test count;
• the new erosion-rate and resonance controls were not consistently documented;
• source distributions did not explicitly retain the complete research-software documentation set;
• CI tested the editable source tree but did not build and inspect release distributions;
• citation metadata did not include full author names, repository location, or the concept DOI.

This PR closes those gaps without changing solver mathematics or runtime behaviour.

Validation

python -m pip install -e ".[dev]"
python -m py_compile tests/test_project_metadata.py
python -m pytest tests/test_project_metadata.py
python -m pytest
python -m pre_commit run --all-files
python -m build
python -m twine check dist/*
python -m pip install --force-reinstall --no-deps dist/*.whl
ldsfl-run --help

A short solver smoke test remains recommended after reinstalling the wheel:

python -m run_ldsfl --base-dir . --cases 1 --max-steps 1 --no-plots --erosion-rate 1e-8

Compatibility

• Package and citation version remain 0.6.5.
• Solver defaults and numerical algorithms are unchanged.
• CLI and GUI behaviour are unchanged.
• The historical erosion-rate default remains 1.0e-8.
• Existing input and output file schemas are unchanged.
• The GUI remains a source-checkout workflow; this PR does not add a new installed GUI entry point.

Notes

This is the final patch-12 housekeeping PR. It intentionally avoids:

• changing the numerical model;
• changing the adaptive timestep;
• adding new solver options;
• changing output naming;
• creating a release tag;
• publishing to PyPI or Zenodo.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a3efc22477

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Include linked docs and example assets in the sdist

For source distributions, these patterns include the README, docs, and example READMEs but omit files those included docs depend on: docs/figures/*.png is referenced by the README and the LaTeX manual source, while docs/run_manifest_template.md links to examples/run_manifest_template.yml, and the reproducible example README points to regenerate.py and expected_tree.txt. An unpacked sdist therefore has broken documentation/reproducibility instructions despite this manifest being added to preserve those materials; include the linked asset/script/template extensions as well.

Useful? React with 👍 / 👎.

[sergioald]

Thanks — valid finding.