Skip to content

Event catalog pages render the raw docstring inside the JSON schema #103

Description

@mmacy

The generated pages under reference/events/ (from tools/docs/gen_schema_reference.py) render each event's class docstring verbatim inside a JSON schema block, and the schema's properties carry no description for any field, because PEP 224 attribute docstrings do not become pydantic field descriptions. Two consequences after #99:

  • mkdocstrings cross-reference syntax such as [`TakeTreasure`][osrlib.crawl.commands.TakeTreasure] appears as literal text on the catalog page.
  • The field prose written in Docstrings: crawl session and events #99 renders in full on the reference/api/osrlib/crawl/events/ page but not on the catalog page, so the catalog is now the weaker of two views of the same event. The catalog page does link the API page as "Full documentation".

Options: render the class docstring through the Markdown pipeline instead of inside the schema block, or drop the docstring from the schema and let the catalog page point at the API page, or derive field descriptions for the schema from the attribute docstrings at generation time.

Found during the docstring pass (#87 to #99).

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

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions