Skip to content

Docs: README fixes — empty section, misleading Makefile usage, redundant setup steps, undocumented runall options #31

Description

@msleigh

Problems

In README.md (and mirrored text in mkdocs/getting-started.md):

  1. The "Dependencies → Documentation" section is empty (line ~66). List: MkDocs + Material, Ford (optional), Zensical (experimental).
  2. "Each part of the project has its own Makefile which can be invoked directly:" followed by ./fortran/src/Makefile etc. — Makefiles are not executables. Reword to show make -C <dir> <target> only (the correct examples already follow).
  3. Redundant environment setup: uv venv + source .venv/bin/activate + uv syncuv sync alone creates the venv; activation is unnecessary when commands are run via uv run (as runall and the docs Makefile expect). Simplify to uv sync and mention uv run usage. Apply to both README and getting-started page.
  4. runall options are undocumented: -u (regenerate known-good outputs) and the ABS_TOL/REL_TOL environment variables. Add a short "Updating known good outputs" subsection.
  5. The Black code-style badge is stale once ruff lands (Add ruff (lint + format) and shfmt to pre-commit and pyproject #19) — coordinate.
  6. docs/TODO.md items that now have issues should be replaced by links to those issues (or the file trimmed to only untracked ideas), so there is a single source of truth.

Verification

  • make -C docs html builds cleanly; proofread rendered pages. British English, Oxford comma, plain English.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationmodel: haikuSuitable for Haiku (mechanical, well-specified)priority: lowFix when convenient

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions