docs: fix sphinx doc generation and update docstrings
Metadata
Current evaluation
Merged in canonical/craft-parts#65 via a5373f23, fixing Sphinx type-hint import cycles and adding missing docstring parameter descriptions.
Resolution: closed resolved
Reason: PR #65 was merged as a5373f23. It changed Sphinx-sensitive type-hint imports to module imports to avoid cycles and completed missing parameter descriptions.
Evaluated by: mr-cal-bot
No scores available.
Issue body
Sphinx type hints are very sensitive to import cycles. In such case,
import only the module instead of classes/functions as explained in
the sphinx-autodoc-typehints documentation.
Also add missing parameter descriptions to docstrings.
- [x] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
-----
Evaluation history
| Date | Model | Scores | Action | Summary |
|---|---|---|---|---|
| stealth/space-bunny-alpha | — | closed resolved | Merged in canonical/craft-parts#65 via a5373f23, fixing Sphinx type-hint import cycles and adding missing docstring parameter descriptions. | |
| stealth/space-bunny-alpha | — | closed resolved | Merged in canonical/craft-parts#65 (a5373f23): changed Sphinx type-hint imports to module imports to avoid import cycles and added missing docstring parameter descriptions. | |
| qwen/qwen3.6-35b-a3b | — | — | Merged after two approvals and passing CI. Fixed Sphinx doc generation by importing modules to resolve import cycles, and added missing parameter descriptions to docstrings across five files. | |
| qwen3.6-35b-a3b-mtp-q6 | — | — | Merged documentation updates that resolve Sphinx generation failures caused by import cycles by switching to module-level imports. Added missing parameter descriptions to docstrings. |
Update history
No update history recorded yet.
Related issues
| Issue | Project | State | Summary | Similarity |
|---|---|---|---|---|
| #720 docs: use canonical-sphinx | craft-parts | merged | Merged PR #720 as commit 278feb8d, migrating craft-parts docs to canonical-sphinx and removing legacy configuration across three files. | |
| #562 docs: update to canonical-sphinx | craft-providers | merged | Merged PR (commit 9897239) enabled the canonical-sphinx docs extension and removed sphinx-docs-starter-pack submodule references in craft-providers. Leftover submodule dir was later cleaned up in #713. | |
| #346 docs: update sphinx-autodoc-typehints | craft-parts | merged | Merged PR craft-parts#346 (commit 96d63c25) bumping sphinx-autodoc-typehints to fix broken Sphinx autodoc generation caused by the extension's poor interaction with Pydantic. | |
| #486 docs: fixed broken references | craft-parts | merged | Merged as canonical/craft-parts#486 via commit fd734825, correcting broken documentation references in four files; rebasing onto main cleared a Pydantic 2-related mypy failure. | |
| #40 docs: update and fix doc generation | craft-providers | merged | Merged docs-generation fixes in #40 via commit 6897a11 (merge c0b6bf2), adding sphinx-pydantic, executor/base reference sections, and refreshed requirements. | |
| #4367 docs: update sphinx theme | snapcraft | merged | Merged as commit aa64666ef, updating the Sphinx documentation theme; it replaced earlier attempt #4263 and picked up the #4375 fixes that restored broken doc builds. | |
| #434 docs: use tox for sphinx docs | craft-parts | closed | Closed unmerged as redundant: canonical/craft-parts#433 merged the broader Starbase tox setup in 7dbf0405; equivalent Sphinx support landed via canonical/snapcraft#4273 at d25b49d63. | |
| #325 docs: use canonical-sphinx | craft-application | merged | Merged PR #325 in commit 8ca97e1a, migrating the docs to canonical-sphinx and removing unused extensions and configuration. | |
| #412 docs: fix list syntax | craft-parts | merged | Merged canonical/craft-parts#412 as cebfdc2e, correcting documentation list syntax errors introduced by an earlier change. | |
| #209 docs: use canonical-sphinx | starbase | merged | Merged PR #209 (commit cd48e13) migrated the documentation build from legacy Sphinx configuration to canonical-sphinx. |