Fix doc references - #896
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adjusts BayBE’s Sphinx documentation setup to fix broken/incorrect references and to make internal link checking stricter (no longer skipping relative/internal links), primarily by refining Sphinx config suppressions and doc cross-reference targets.
Changes:
- Move recursive API autosummary stub generation off the docs landing page and into a dedicated page.
- Expand/refine
nitpick_ignore_regexand Sphinx warning suppressions to reduce false-positive doc reference failures. - Fix several incorrect Sphinx roles/options in docs and docstrings (
:class:vs:obj:, MyST admonition options, fully-qualified refs).
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/templates/custom-module-template.rst | Adjusts autosummary module listing (now excludes kmedoids). |
| docs/index.md | Removes inline autosummary generation from the landing page. |
| docs/conf.py | Reworks nitpick ignore regexes and warning suppression for stricter link/ref checking. |
| docs/components/transformations.md | Fixes MyST admonition option syntax. |
| docs/api_reference.md | Adds a dedicated page intended to trigger recursive autosummary stub generation. |
| baybe/transformations/base.py | Fixes docstring cross-references to the Transformation base class. |
| baybe/surrogates/gaussian_process/core.py | Fixes a docstring reference role to match a runtime type alias/protocol pattern. |
| baybe/recommenders/meta/base.py | Fixes a docstring method reference to a fully-qualified target. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| @@ -23,16 +23,6 @@ FAQ <faq> | |||
| :relative-docs: docs/ | |||
| ``` | |||
|
|
|||
There was a problem hiding this comment.
Not sure that this is actually an issue as the hidden directive is actually what caused issues, but I will investigate.
There was a problem hiding this comment.
Should be handled via orphan, will simply check in the doc
| ( | ||
| r"py:.*", | ||
| r"(pandas|numpy|torch|botorch|gpytorch|scipy|sklearn|pathlib|polars|attr|joblib|matplotlib|skfp|rdkit|shap|xyzpy|typing)[\._].*", | ||
| ), # noqa: E501 |
There was a problem hiding this comment.
Might be reasonable.
| :recursive: | ||
| {% for item in modules %} | ||
| {% if not item in ("baybe.objectives.deprecation", "baybe.recommenders.pure.bayesian.sequential_greedy") %} | ||
| {% if not item in ("kmedoids",) %} |
There was a problem hiding this comment.
Need to verify this in the doc.
25d3e46 to
5ed61c4
Compare
… `baybe` This ignore helped in keeping the list of `nitpick_ignore_regex` small, but caused issues as this also means that relative internal links have not been checked, causing a lot of silent errors.
Since we now no longer simply ignore everything that does not contain `baybe`, the list needs to be extended manually.
5ed61c4 to
17b2782
Compare
There was a problem hiding this comment.
BLOCKER: Check first that this builds the documentation properly on my fork
This PR fixes incorrect doc references and makes some general changes to how we check our internal links.
The core issue that is fixed here is that we previously ignored all links that do not contain or start with baybe. As a consequence, internal relative links were being skipped, and if those links were broken, we simply didn't know. This was now removed. As a consequence, we however now need to manually add a lot of additional regexes that we need to ignore now. I still need to investigate if all of these are actually necessary, so this list it self might still change.
Stack created with GitHub Stacks CLI • Give Feedback 💬