You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
The generated pages under
reference/events/(fromtools/docs/gen_schema_reference.py) render each event's class docstring verbatim inside a JSON schema block, and the schema'spropertiescarry nodescriptionfor any field, because PEP 224 attribute docstrings do not become pydantic field descriptions. Two consequences after #99:[`TakeTreasure`][osrlib.crawl.commands.TakeTreasure]appears as literal text on the catalog page.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).