Skip to content

v0.17.0

Latest
Latest

Choose a tag to compare

View all tags
@rich-iannone rich-iannone released this 13 Aug 15:21
· 156 commits to main since this release
v0.17.0
1ce8eb8

Great Docs v0.17.0 is a fairly large release, with many great improvements across the board. The big additions are: (1) Marimo notebook integration (live, reactive notebooks embedded directly in your docs site), (2) Rust CLI documentation support (mirroring the existing Go CLI feature), and (3) a new CI preview workflow that lets reviewers fetch and open a PR's built site locally (no preview host required for this). This release also brings PEP 695 type alias support, explicit navbar ordering, and a little bit of polish to the MCP index page and homepage metadata sidebar.

New Features

  • Marimo notebook integration — Marimo notebooks can now be embedded as live, reactive islands in your documentation site using the marimo Quarto shortcode. The runtime version is pinned to your installed marimo package automatically, and all required CDN assets are injected into <head> at build time. (#307)

  • Rust CLI documentation — Rust projects using clap, structopt, or a custom --help interface are now auto-detected and documented as a CLI reference section, matching the existing Go CLI feature. (#315)

  • CI site preview — A new great-docs preview command fetches the HTML artifact that CI already uploaded for a PR or workflow run, unpacks it into a local cache, and opens it in your browser (no Netlify or Cloudflare Pages needed). A sticky PR comment posted by the CI step tells reviewers the exact commands to run. (#305, #306)

  • Navbar ordering — A new navbar_order config option accepts an ordered list of navbar labels, letting you pin the sequence of top-level navigation items regardless of the order they are added during the build. (#310)

Enhancements

  • PEP 695 type alias support — Type aliases written with the type X = ... syntax (PEP 695, Python 3.12+) are now fully documented alongside TypeAlias-annotated attributes and rendered under a dedicated "Type Aliases" section. (#296)

  • Config defaults are now kept exclusively in great-docs.default.yml as a single source of truth; config.py holds no default values of its own, making it easier to audit and extend the config surface. (#292)

  • Dynamic introspection no longer builds self-referential aliases, preventing infinite loops in packages that re-export their own members. (#294)

  • Each docstring section (Parameters, Returns, Raises, etc.) is now rendered only on the pages where it is meaningful, eliminating empty sections on summary and index pages. (#308)

  • Attributes are now documented correctly when dynamic=True is set on a class or module. (#309)

Bug Fixes

  • Triple curly braces in code includes ({{{…}}}) are now correctly escaped so they pass through to the rendered output unchanged. (#290)

  • Dark-mode images now load on the initial page state instead of only after a theme toggle. (#298)

  • The MCP reference section is no longer missing when building against MCP v2+ due to an API incompatibility. (#300)

  • The MCP index page now uses details-based callouts for tool listings and received additional content and layout refinements. (#302, #313, #316)

  • Navigation bar logos with a computed size of 0 are now skipped to avoid invisible broken image elements. (#301)

  • Sidebar subsections now preserve the source order defined in the config rather than being reordered during the build. (#299)

  • Metadata sidebar CSS on the homepage (when the homepage is configured to be the first page of the User Guide) was corrected for layout and alignment. (#317)

Documentation

  • Added step-by-step Great Docs upgrade instructions for maintainers to both the published skill and the User Guide. (#311)

  • Added user-facing guidance for less-documented object types (type aliases, TypeVars, protocols, etc.) in the User Guide. (#314)

New Contributors

Contributors

Sanjays2402
Assets 2
Loading