docs: fix API reference completeness and navigation (#888)#889
Open
egordm wants to merge 2 commits into
Open
Conversation
- Add openstef_meta package to API index (models, presets, utils) - List transforms submodules explicitly (general, time_domain, energy_domain, weather_domain, validation) — fixes empty page - Add missing modules: workflows, presets, integrations, utils, mixins - Remove phantom entries: pipelines, exceptions (eliminated build warnings) - Add autodoc hook to render Pydantic Field(description=...) values - Collapse sidebar navigation by default (was 95+ items expanded) - Add Meta card to API landing page grid Closes #888 Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com> Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com> Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com>
… descriptions - Add dynamic submodule discovery via pkgutil.iter_modules() in conf.py (registered through autosummary_context for Jinja2 templates) - Add Pydantic field description injection via object-description-transform event, placing descriptions next to attribute type annotations - Create per-package API sub-pages (core, models, beam, meta) with :recursive: autosummary for automatic child module documentation - Remove hardcoded submodule lists from package_overview.rst template, replaced with discover_submodules() calls - Remove hardcoded drill-down sections from models.rst and meta.rst - Fix short_name threshold (>3 to >=3) in both templates for correct sidebar labels on 3-part module names - Update index.rst summary tables to match actual package contents - Add missing modules: transforms (models pkg), mixins/testing/ transforms/types (core pkg) Resolves #888 Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com> Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com> Signed-off-by: Egor Dmitriev <egor.dmitriev@alliander.com>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes the API reference to cover the full public surface with navigable hierarchy. Resolves #888.
Changes
Coverage
openstef_metasection added to API index (models, presets, utils)openstef_models.transformsnow lists all 6 submodules and their public classesworkflows,presets,integrations,utils,mixins,transforms(models),mixins,testing,transforms,types(core)pipelines,exceptions)autosummary.import_cyclewarnings (suppressed as benign)Pydantic rendering
Field(description=...)values shown alongside field definitions viaobject-description-transformhook (~30 LOC in conf.py, no new dependencies)Navigation
collapse_navigation: True— sidebar collapsed by defaultTemplate improvements
pkgutil.iter_modules()registered throughautosummary_context— no hardcoded module names in templatesshort_namethreshold (>3→>=3) for correct sidebar labels on nested modules:recursive:autosummary for automatic child module documentationSpot-checks
openstef_models.transforms.general— shows OutlierHandler, Imputer, Scaler with docstringsBacktestConfig— shows "Time interval between prediction samples..."openstef_meta.presets— renders with classes and functionsRemaining warnings (pre-existing, not introduced)
stub file not foundforopenstef_core.mixins.{predictor,stateful,transform}— macOS case-insensitive filesystem collision (Predictor.rstoverwritespredictor.rst)failed to import SimpleTargetProvider[BenchmarkTarget,— generic type annotation with brackets confuses autosummary parser