Skip to content

Consolidate the mkdocs config reading, the docs root, and the stamp constants #9

Description

@mairas

From the review on PR #1: #1 (comment)

Three reviewers independently reached the same conclusion about the shape of the extraction.

  • _Loader and its multi-constructor now exist verbatim in two modules, and four of six modules read mkdocs.yml — three of them by importing configured_languages from translation_status, which makes the translation report a library for the anchor checker. check-anchors is the one command docs.halos.fi runs and the one with nothing to do with translations. Consolidating is right, but not into translation_status. A mkdocs_config.py holding _Loader, configured_languages() and configured_base() is one small module with five callers.
  • The docs root is treated five ways across six commands: a module constant in two, an inline Path("docs") in one, an inline Path("docs", language) in another, and a --docs option in the fifth. A reader cannot tell from any one module whether it is configurable, and the next command has five precedents to choose from.
  • STAMP_KEY and blob_hash are declared independently in the module that writes the stamp and the one that reads it. STAMP_KEY is the on-disk format contract between them; PR Package the documentation checkers and add a blocking translation gate #1 had to edit blob_hash in both places to add --no-filters, which is exactly the failure this invites.
  • The five entry states are bare strings with the set written out twice in the two renderers and "current" compared as a literal in four places. This is the vocabulary of a blocking gate: a typo in one comparison is a permanent pass or a permanent fail, and nothing type-checks it.
  • chain_rule = () if allowed else HYPHEN_CHAINS.finditer(text) binds one name to two unrelated types, eight lines above an adjacent rule that uses a plain conditional.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions