Fix postgkyl Documentation API Path References
So the documentation has the python API listed like gk diagnostics postgkyl.diagnostics.gk.load_distf postgkyl.diagnostics.gk.resolve_frames postgkyl.diagnostics.gk.available_quantities postgkyl.diagnostics.gk.load_quantity
I thought calling these would be like postgkyl.gk.load_quantity(). So why is .diagnostics given here? Is that important or is it a miscommunication?
I’ll check how the API is exposed and how the documentation gets those names.
Your understanding is correct: postgkyl.gk.load_quantity(...) is the intended public spelling, or:
The package exposes the gk module directly in its top-level API. Both paths refer to the same functions; .diagnostics is not required when calling them.
The longer names appear because the documentation generator uses the module’s internal __name__, which remains postgkyl.diagnostics.gk even when exposed as postgkyl.gk.
So this is a documentation presentation mismatch. diagnostics matters for internal code organization, but the user-facing reference should show postgkyl.gk.* to match how you’re expected to use it.
Fix the documentation to represent the user-facing way that these would be called. So if the path is exposed to the top-level API, then use that, but otherwise use .diagnostics. So in this example, gk is presented as postgkyl.gk.load_quantity()
I’ll update the generator to prefer top-level API paths and keep .diagnostics for namespaces that aren’t exposed there. I’m using the design, API/CLI, and development skills for this change.
The generator already prefers top-level paths for individual functions. I’ll extend that to module exports such as gk, and verify that the rendered API pages and CLI links use the new paths while other diagnostics retain .diagnostics. I’m also using the testing skill for that verification.
The generated reference now uses postgkyl.gk.*, including the quantity reference and CLI links. Namespaces without a top-level export still use postgkyl.diagnostics.*. Those checks passed; the documentation build and remaining tests are still running.
The documentation built successfully with warnings treated as errors, and the rendered page shows postgkyl.gk.load_quantity. The broader suite passed with 1,982 tests and 6 skips. The final documentation checks are still running the downloadable examples.
Updated the documentation generator to prefer top-level exports, so GK functions appear as postgkyl.gk.load_quantity(). Other namespaces retain .diagnostics. Cross-links use the same paths.
Verified the rendered documentation and full test suite: 1,988 passed, 6 skipped.