diff --git a/docs/user_guide/05-configuration.qmd b/docs/user_guide/05-configuration.qmd index c422fe4bc..0b1515cb6 100644 --- a/docs/user_guide/05-configuration.qmd +++ b/docs/user_guide/05-configuration.qmd @@ -322,6 +322,19 @@ the build. Your own site publishes `objects.inv` at its root, so other projects can point a source at your documentation in the same way. +### Aliases for Your Own Package + +`interlinks.aliases` lists the module names your prose uses for your own package. With +`aliases: [sc]` for Sciris, `` `sc.findinds()` `` and `` [](`sc.findinds`) `` both resolve as +`sciris.findinds`: + +```yaml +interlinks: + aliases: [sc] +``` + +If a source lists the same alias, yours wins. + ### Parentheses on Function Links A function or method link displays a trailing `()`, so `[](`decode`)` renders as `decode()`. Class diff --git a/docs/user_guide/06-api-documentation.qmd b/docs/user_guide/06-api-documentation.qmd index a0f97a71b..658e25a24 100644 --- a/docs/user_guide/06-api-documentation.qmd +++ b/docs/user_guide/06-api-documentation.qmd @@ -728,6 +728,45 @@ Quarto rendering) but differ in where configuration lives and how much you need 5. **Build and preview.** Run `great-docs build` followed by `great-docs preview`. Your reference pages should render with the same content, now with Great Docs' enhanced styling and features. +### Keeping quartodoc for the API Reference + +If you'd rather keep your quartodoc reference pages exactly as they are, Great Docs can run +quartodoc for you instead of generating the reference itself. Install a quartodoc distribution, +such as the maintained [quartopydoc](https://github.com/sciris/quartopydoc) fork: + +```bash +pip install great-docs[quartodoc] +``` + +Then copy the `quartodoc:` block from your `_quarto.yml` into `great-docs.yml` unchanged: + +```{.yaml filename="docs/great-docs.yml"} +quartodoc: + package: my_package + style: pkgdown + dir: api + sections: + - title: Core + desc: Primary interface + contents: + - MyClass + - helper_function +``` + +On each build, quartodoc writes the reference pages in place of Great Docs, and its sidebar +(grouped by your sections) becomes the reference sidebar, with no `metadata-files` entry needed. +Everything else about the API stays Great Docs': it still discovers your API (honoring `reference` +and the other settings on this page) for `llms.txt`, `llms-full.txt`, and the agent skill, and +cross-references across the site resolve to quartodoc's pages too. `llms.txt` links to quartodoc's +pages, listing only the objects quartodoc documents. +`package` defaults to your detected package and `dir` to `reference`; the navbar's Reference link +follows `dir`. Any other quartodoc option works as it does in quartodoc, including `sidebar` +options such as `collapse-level`. + +To also carry over your site's appearance, see [Raw Quarto Settings](theming.qmd#quarto-passthrough). +If your docs write names with a module alias, such as `sc.findinds()` for `import sciris as sc`, +set `interlinks.aliases` (see [Cross-Referencing](cross-referencing.qmd)) so they link too. + ## Next Steps Great Docs handles the tedious parts of API documentation (discovery, classification, layout, diff --git a/docs/user_guide/11-theming.qmd b/docs/user_guide/11-theming.qmd index da1b540cd..2a245706b 100644 --- a/docs/user_guide/11-theming.qmd +++ b/docs/user_guide/11-theming.qmd @@ -565,13 +565,21 @@ format: ``` ::: {.callout-warning} -Replacing a list replaces Great Docs' own entries too. For example, setting `format.html.theme` -drops `great-docs.scss`, the stylesheet behind most of Great Docs' styling, and setting +Replacing a list replaces Great Docs' own entries too. For example, setting `format.html.include-in-header` drops the scripts Great Docs injects. For everyday settings, prefer -`site` (which merges into `format.html` before Great Docs adds its own entries), `include_in_header`, -and the other dedicated options on this page. +`site`, `include_in_header`, and the other dedicated options on this page. The one exception is +`format.html.theme`: Great Docs puts its own stylesheet, `great-docs.scss`, back in right after the +base theme, since its widgets need it, so your SCSS files still take precedence. ::: +To keep the look of an existing site's pages entirely, also set `styles: widgets`. Great Docs then +styles only its own widgets and the page layout, leaving page content (heading and code fonts, +link and table styles) to your Quarto theme and SCSS: + +```{.yaml filename="docs/great-docs.yml"} +styles: widgets +``` + ## Logo Great Docs can display a logo in the navbar instead of the plain-text package name. Logos are diff --git a/docs/user_guide/12-cross-referencing.qmd b/docs/user_guide/12-cross-referencing.qmd index 808d81948..b0f742bc3 100644 --- a/docs/user_guide/12-cross-referencing.qmd +++ b/docs/user_guide/12-cross-referencing.qmd @@ -60,6 +60,14 @@ See [](`numpy.ndarray`) for the array type, or [](`np.ndarray`) using the alias. Code autolinks stay inside your own project. A bare `` `array` `` in your prose is left alone rather than linked into another project's documentation. +Your own package can have an alias too. If your users write `import sciris as sc`, list `sc` under +`interlinks.aliases`, and `` `sc.findinds()` `` in your prose links to `sciris.findinds()`: + +```yaml +interlinks: + aliases: [sc] +``` + See [Configuration](05-configuration.qmd) for the full set of fields a source accepts. ## When a Short Name Is Ambiguous diff --git a/great_docs/_interlinks/index.py b/great_docs/_interlinks/index.py index 36a3af8e9..f3b8fe778 100644 --- a/great_docs/_interlinks/index.py +++ b/great_docs/_interlinks/index.py @@ -222,6 +222,7 @@ def build_index( claims: AliasClaims, external: Sequence[tuple[Source, Inventory]], *, + aliases: Sequence[str] = (), add_function_parentheses: bool = True, ) -> Index: """ @@ -240,6 +241,9 @@ def build_index( The short names this project's documented objects claim. external : Each source and the inventory read for it. + aliases : + Module aliases prose uses for this project's own package. They win + over a source's alias of the same spelling. add_function_parentheses : Whether a link to a function or method shows a trailing `()`. @@ -282,6 +286,8 @@ def add(name: str, rank: int, priority: int, entry: IndexEntry) -> None: roots = root_modules(inv) for alias in source.aliases: prefixes[alias] = roots + for alias in aliases: + prefixes[alias] = root_modules(local) ordered = { name: tuple(entry for _, entry in sorted(items, key=lambda pair: pair[0])) diff --git a/great_docs/_interlinks/project.py b/great_docs/_interlinks/project.py index 4c645484c..19e5e1251 100644 --- a/great_docs/_interlinks/project.py +++ b/great_docs/_interlinks/project.py @@ -64,6 +64,7 @@ def build_project_index( local, claims, sources.read, + aliases=config.interlinks_aliases, add_function_parentheses=config.interlinks_add_function_parentheses, ) write_index(index, project_path / "_inv" / "index.lua") diff --git a/great_docs/_lint.py b/great_docs/_lint.py index aa89f8451..d5be7170b 100644 --- a/great_docs/_lint.py +++ b/great_docs/_lint.py @@ -237,6 +237,7 @@ def run_lint( create_inventory(importable_name, "", documented), AliasClaims.make(documented), sources.read, + aliases=docs._config.interlinks_aliases, ) _check_cross_references( pkg, importable_name, exports, documented, index, sources.unread, result diff --git a/great_docs/_utils.py b/great_docs/_utils.py index 3d3948e69..a4ffd2556 100644 --- a/great_docs/_utils.py +++ b/great_docs/_utils.py @@ -145,6 +145,39 @@ def merge_quarto_overrides(config: dict, overrides: dict) -> dict: return result +GREAT_DOCS_SCSS = "great-docs.scss" + + +def with_great_docs_scss(theme: str | list | dict, position: int | None = None) -> str | list | dict: + """ + Add great-docs' stylesheet to a Quarto `theme` value + + Handles each form `theme` takes: a theme name, a list of themes and SCSS + files, or a mapping of such values by mode (`light`, `dark`). A value that + already includes the stylesheet is returned unchanged. + + Parameters + ---------- + theme + The `format.html.theme` value. + position + Where to insert the stylesheet in each list; `None` appends it, so it + overrides the rest, while `1` puts it right after the base theme, so + the user's own SCSS files override it. + + Returns + ------- + str | list | dict + The theme value with the stylesheet added. + """ + if isinstance(theme, dict): + return {mode: with_great_docs_scss(value, position) for mode, value in theme.items()} + themes = [theme] if isinstance(theme, str) else list(theme) + if GREAT_DOCS_SCSS not in themes: + themes.insert(len(themes) if position is None else position, GREAT_DOCS_SCSS) + return themes + + GITIGNORE_CONTENT = """# Great Docs build directory # This directory is ephemeral and regenerated on each build # Do not commit this directory to version control diff --git a/great_docs/assets/great-docs.default.yml b/great_docs/assets/great-docs.default.yml index b20bdec96..f74f22e2a 100644 --- a/great_docs/assets/great-docs.default.yml +++ b/great_docs/assets/great-docs.default.yml @@ -58,6 +58,9 @@ parser: numpy # aliases: [np] interlinks: sources: {} # Projects to link to; none by default + # Module aliases your prose uses for this project's own package, so that + # `sc.findinds()` links like `sciris.findinds()` (for `import sciris as sc`). + aliases: [] # A link to a function or method shows a trailing "()", as `decode()` rather # than `decode`. Links to classes never show one. add_function_parentheses: true @@ -274,6 +277,17 @@ site: # mainfont: "Source Sans Pro" quarto: {} +# Styles +# ------ +# What Great Docs styles. Its widgets (navbar buttons, copy buttons, badges and +# the like) and page layout are always styled; page content (heading and code +# fonts, link and table styles) is optional. +# : all - (default) the whole page +# : widgets - only the widgets and layout, leaving page content to the Quarto +# theme and any SCSS you add to it (for example, to keep the look of an +# existing Quarto site) +styles: all + # Page Metadata # ------------- # Show page timestamps in footer @@ -409,6 +423,25 @@ csl: null # - another_func reference: [] +# quartodoc API Reference +# ----------------------- +# Generate the API reference with quartodoc (e.g. the quartopydoc fork, +# `pip install great-docs[quartodoc]`) instead of great-docs' own renderer. +# Takes the same settings as the `quartodoc:` block of a Quarto project's +# `_quarto.yml`, so an existing block can be copied over unchanged. `package` +# defaults to the detected package and `dir` to "reference". When set, the +# `reference` option above is ignored. +# +# quartodoc: +# style: pkgdown +# parser: google +# sections: +# - title: Utilities +# desc: Helper functions +# contents: +# - mymodule +quartodoc: {} + # Inline Methods # -------------- # Whether class methods get their own pages or stay inline. diff --git a/great_docs/assets/great-docs.scss b/great_docs/assets/great-docs.scss index 37197f1dc..942e97c66 100644 --- a/great_docs/assets/great-docs.scss +++ b/great_docs/assets/great-docs.scss @@ -5,8 +5,19 @@ // - https://getbootstrap.com/docs/5.3/utilities/text /*-- scss:defaults --*/ -$h2-font-size: 1.5rem; -$h3-font-size: 1.3rem; +// Whether great-docs styles page content as well as its own widgets and the +// page layout: heading and code fonts, link and table styles and the like. +// `styles: widgets` in great-docs.yml sets it to false, leaving page content +// to the Quarto theme and the user's SCSS. +$gd-content-styles: true !default; + +// Declared without a value, so the user's SCSS or else Bootstrap sets them +$h2-font-size: null !default; +$h3-font-size: null !default; +@if $gd-content-styles { + $h2-font-size: 1.5rem !global; + $h3-font-size: 1.3rem !global; +} /*-- scss:mixins --*/ $headings-font-weight: 300 !default; @@ -45,8 +56,10 @@ $member-groups: "section:is(.doc-attributes, .doc-classes, .doc-type-aliases, .d $ref-page: "body:is(.doc-reference, .doc-api-page)"; $ref-index-links: 'a.sidebar-item-text:is([href$="/index.html"], [href$="/"])'; -a { - text-decoration: none; +@if $gd-content-styles { + a { + text-decoration: none; + } } a.gdls-link { @@ -98,28 +111,30 @@ span.gd-linkback-text { display: none; } -// Set headings boldness back to the bootstrap default. -// quarto changes it for h1, h2, h3! -h1, .h2, h2, .h2, h3, .h3 { - @extend .fw-medium; -} +@if $gd-content-styles { + // Set headings boldness back to the bootstrap default. + // quarto changes it for h1, h2, h3! + h1, .h2, h2, .h2, h3, .h3 { + @extend .fw-medium; + } -// Title headings get extra weight -h1.title { - font-weight: 600 !important; -} + // Title headings get extra weight + h1.title { + font-weight: 600 !important; + } -// Title headings get a larger font size on desktop -@media (min-width: 992px) { - h1.title, .title.h1 { - font-size: 2.3rem; + // Title headings get a larger font size on desktop + @media (min-width: 992px) { + h1.title, .title.h1 { + font-size: 2.3rem; + } } -} -// Remove h2 underline (Quarto/Bootstrap adds border-bottom to h2 elements) -h2, .h2 { - border-bottom: none; - padding-bottom: 0; + // Remove h2 underline (Quarto/Bootstrap adds border-bottom to h2 elements) + h2, .h2 { + border-bottom: none; + padding-bottom: 0; + } } // Changelog version headings: add a Lucide-style tag glyph and code-like type. @@ -149,8 +164,10 @@ body.gd-changelog-page .gd-otp-panel-link { font-family: $font-family-monospace; } -h5, .h5 { - @extend .mt-3; +@if $gd-content-styles { + h5, .h5 { + @extend .mt-3; + } } header p { @@ -165,8 +182,10 @@ header p { } } -table:not(.gt_table) { - @extend .table-bordered; +@if $gd-content-styles { + table:not(.gt_table) { + @extend .table-bordered; + } } // Summary tables used in reference pages (Methods, Attributes sections) @@ -925,14 +944,16 @@ html:not(.theme-loaded) body { opacity: 0.25; } -.table a { - text-underline-offset: 4px; - font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; - color: inherit; - font-weight: bold; - font-size: 0.875em; - word-break: initial; - text-decoration-thickness: 2px; +@if $gd-content-styles { + .table a { + text-underline-offset: 4px; + font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; + color: inherit; + font-weight: bold; + font-size: 0.875em; + word-break: initial; + text-decoration-thickness: 2px; + } } /* Callable name in a `plain` signature, such as `add_node` in `Graph.add_node`. */ @@ -1003,16 +1024,12 @@ body { background-color: var(--gd-bg-primary, #FCFEFF); } -p a { - color: black; - text-decoration: underline; - text-underline-offset: 4px; -} - -li a { - color: black; - text-decoration: underline; - text-underline-offset: 4px; +@if $gd-content-styles { + p a, li a { + color: black; + text-decoration: underline; + text-underline-offset: 4px; + } } /* ========================================================================== @@ -1336,10 +1353,12 @@ dd > ol > li::marker { text-indent: 0; } -code { - font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; - font-size: 0.875em; - color: rgb(18, 18, 18); +@if $gd-content-styles { + code { + font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; + font-size: 0.875em; + color: rgb(18, 18, 18); + } } .blockquote { @@ -1348,8 +1367,10 @@ code { border-left-color: #4682B4; } -p,h1,h2,h3,#toc-title,#toc-function-reference,.nav-link,.table { - font-family: "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; +@if $gd-content-styles { + p,h1,h2,h3,#toc-title,#toc-function-reference,.nav-link,.table { + font-family: "Open Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; + } } /* Great Tables (gt) ship their own font as a self-contained component. The diff --git a/great_docs/config.py b/great_docs/config.py index 072be4edb..bf4fd2c07 100644 --- a/great_docs/config.py +++ b/great_docs/config.py @@ -932,6 +932,20 @@ def reference_enabled(self) -> bool: return False return True + @property + def quartodoc(self) -> ConfigDict: + """Get the quartodoc settings that replace great-docs' own API reference. + + Empty unless the user asked for quartodoc to build the API reference. + """ + quartodoc = self["quartodoc"] + if not isinstance(quartodoc, dict): + raise ValueError( + f"`quartodoc` in great-docs.yml must be a mapping of quartodoc settings, " + f"not {type(quartodoc).__name__}" + ) + return cast("ConfigDict", quartodoc) + @property def reference(self) -> list[ConfigDict]: """Get the API reference configuration (explicit section ordering). @@ -1059,6 +1073,14 @@ def quarto(self) -> ConfigDict: ) return cast("ConfigDict", quarto) + @property + def styles(self) -> str: + """What great-docs styles: "all" of the page, or only its "widgets" and layout.""" + styles = self["styles"] + if styles not in ("all", "widgets"): + raise ValueError(f'`styles` in great-docs.yml must be "all" or "widgets", not {styles!r}') + return styles + @property def show_dates(self) -> bool: """Whether to show page metadata timestamps in the footer.""" @@ -1117,6 +1139,12 @@ def interlinks_sources(self) -> ConfigDict: """Get the external documentation projects to link to.""" return cast("ConfigDict", self["interlinks.sources"]) + @property + def interlinks_aliases(self) -> list[str]: + """Get the module aliases prose uses for this project's own package, such as `sc`.""" + aliases = self["interlinks.aliases"] + return [aliases] if isinstance(aliases, str) else list(aliases or []) + @property def interlinks_add_function_parentheses(self) -> bool: """Whether function and method links display a trailing `()`.""" diff --git a/great_docs/core.py b/great_docs/core.py index cad351f7f..90800222d 100644 --- a/great_docs/core.py +++ b/great_docs/core.py @@ -28,6 +28,7 @@ validate_build_dir, validate_layout_outputs, validate_tree_symlinks, + with_great_docs_scss, write_quarto_yml, ) from ._website import i18n, markdown_pages, page_dates, page_metadata, page_url, social_cards @@ -51,6 +52,7 @@ from ._apiref.api_reference import APIReference from ._apiref.inventory import InventoryItem + from ._interlinks import AliasClaims # Injected into marimo `--mode edit` WASM exports (iframe mode). Those load inert # — cells are stale and the kernel isn't instantiated, so nothing renders and @@ -105,6 +107,20 @@ class QuartoVersionError(RuntimeError): MIN_QUARTO_VERSION = (1, 9, 18) +def _replace_values(node: Any, old: str, new: str) -> None: + """Replace every string value `old` in a nested config with `new`, in place.""" + items = node.items() if isinstance(node, dict) else enumerate(node) if isinstance(node, list) else () + for key, value in list(items): + if value == old: + node[key] = new + else: + _replace_values(value, old, new) + + +# The file quartodoc writes the API reference sidebar to, unless configured +QUARTODOC_SIDEBAR = "_quartodoc-sidebar.yml" + + def _quarto_version() -> tuple[int, ...] | None: """ Read the version of the Quarto CLI on the `PATH` @@ -308,6 +324,12 @@ def __init__( # Whether API reference was successfully configured (set during build) self._has_api_reference = True + # Whether quartodoc, not great-docs, builds the API reference (set during build) + self._uses_quartodoc = False + + # The page of each object quartodoc documented, by full name (set during build) + self._quartodoc_uris: dict[str, str] = {} + # Whether MCP pages were actually generated (None = not yet determined) self._mcp_pages_generated: bool | None = None @@ -514,8 +536,10 @@ def _prepare_build_directory(self) -> None: print(f"Warning: CSS file not found: {css_path}") # Copy SCSS theme file (contains all site styling) - scss_src = self.assets_path / "great-docs.scss" - shutil.copy2(scss_src, self.build_dir / "great-docs.scss") + scss = (self.assets_path / "great-docs.scss").read_text(encoding="utf-8") + if self._config.styles == "widgets": + scss = scss.replace("$gd-content-styles: true !default;", "$gd-content-styles: false !default;", 1) + (self.build_dir / "great-docs.scss").write_text(scss, encoding="utf-8") # Quarto resolves the signature grammar relative to the build directory. shutil.copy2( @@ -732,6 +756,8 @@ def _prepare_build_directory(self) -> None: self._add_api_reference_config() if self._has_api_reference: self._update_sidebar_from_sections() + if self._config.quartodoc: + self._add_quartodoc_config() # Build the homepage after the API reference configuration. Its metadata # margin can then include links to `llms.txt` and `llms-full.txt` when the @@ -11061,6 +11087,8 @@ def _add_api_reference_config(self) -> None: skips API reference setup entirely and sets `self._has_api_reference = False`. """ + self._uses_quartodoc = False + # Explicit opt-out via great-docs.yml if not self._config.reference_enabled: print("API reference disabled (reference: false), skipping") @@ -11220,6 +11248,142 @@ def _add_api_reference_config(self) -> None: print(f"Added API reference configuration to {quarto_yml}") + def _add_quartodoc_config(self) -> None: + """ + Configure quartodoc to build the API reference pages + + Writes the `quartodoc` block of great-docs.yml into `_quarto.yml`, with + `package` defaulting to the API reference's package and `dir` to + "reference". Great Docs still analyzes the API itself, for llms.txt and + the like; quartodoc only writes the pages. quartodoc is always asked + for a sidebar (with any of the user's `sidebar` options), which + `_build_quartodoc` puts in `_quarto.yml`. + """ + quarto_yml = self.build_dir / "_quarto.yml" + with open(quarto_yml, "r") as f: + config = read_yaml(f) or {} + + qd_config = dict(self._config.quartodoc) + qd_config.setdefault("package", config["api-reference"]["package"]) + qd_config.setdefault("dir", "reference") + sidebar = qd_config.get("sidebar") + sidebar = {"file": sidebar} if isinstance(sidebar, str) else dict(sidebar or {}) + sidebar.setdefault("file", QUARTODOC_SIDEBAR) + sidebar.setdefault("id", "reference") + qd_config["sidebar"] = sidebar + config["quartodoc"] = qd_config + self._uses_quartodoc = True + print(f"Using quartodoc for the API reference pages of package: {qd_config['package']}") + + self._write_quarto_yml(quarto_yml, config) + + def _build_quartodoc(self) -> "AliasClaims": + """ + Build the API reference pages with quartodoc + + Runs in the build directory, which must be the current directory, as + `quartodoc build` would. Afterwards the site links to quartodoc's + pages: the reference sidebar is quartodoc's, links to the reference + index follow its `dir`, `objects.inv` is written from its inventory for + interlinks, and llms.txt is regenerated with its page URLs. + + Returns + ------- + AliasClaims + The short names quartodoc's documented objects claim, for interlinks. + """ + try: + from quartodoc import Builder + except ImportError: + raise RuntimeError( + "The `quartodoc` option in great-docs.yml needs quartodoc installed; " + "install it with `pip install great-docs[quartodoc]`" + ) from None + import sphobjinv as soi + + from great_docs._interlinks import AliasClaims + + quarto_yml = self.build_dir / "_quarto.yml" + builder = Builder.from_quarto_config(str(quarto_yml)) + builder.build() + + # Interlinks read the inventory as objects.inv; llms.txt links by URI + inventory = builder.create_inventory(builder.items) + soi.writebytes(self.build_dir / "objects.inv", soi.compress(inventory.data_file())) + self._quartodoc_uris = {obj.name: obj.uri.replace("$", obj.name) for obj in inventory.objects} + + config = self._read_quarto_config(quarto_yml) + ref_dir = str(builder.dir).strip("/") + if ref_dir != "reference": + _replace_values(config["website"], "reference/index.qmd", f"{ref_dir}/index.qmd") + + sidebar_file = self.build_dir / builder.sidebar["file"] + with open(sidebar_file, "r", encoding="utf-8") as f: + qd_sidebar = (read_yaml(f) or {})["website"]["sidebar"][0] + sidebars = config["website"]["sidebar"] + for i, sb in enumerate(sidebars): + if isinstance(sb, dict) and sb.get("id") == qd_sidebar["id"]: + sidebars[i] = qd_sidebar + break + else: + sidebars.append(qd_sidebar) + self._write_quarto_yml(quarto_yml, config) + + if self._llms_txt_available(): + self._generate_llms_txt() + + # Each object claims its own name; a class member, `Class.member`; and + # an object the package re-exports from a submodule, `package.name` + # (with its members, `package.Class.member`) + package = builder.package + exports = set(self._get_package_exports(package) or ()) + classes = {obj.name for obj in inventory.objects if obj.role == "class"} + modules = {obj.name for obj in inventory.objects if obj.role == "module"} - {package} + + def reexported(name: str) -> str | None: + parent, _, short = name.rpartition(".") + return f"{package}.{short}" if parent in modules and short in exports else None + + claimed = [] + for name in self._quartodoc_uris: + parent, _, short = name.rpartition(".") + claimed.append((short, name)) + if parent in classes: + claimed.append((f"{parent.rpartition('.')[2]}.{short}", name)) + if reexported_class := reexported(parent): + claimed.append((f"{reexported_class}.{short}", name)) + elif reexported_name := reexported(name): + claimed.append((reexported_name, name)) + return AliasClaims(claimed=tuple(sorted(claimed)), published=frozenset(self._quartodoc_uris)) + + def _api_page_url(self, name: str, page_path: str) -> str | None: + """ + Get the site-relative URL of an API object's documentation + + Parameters + ---------- + name + The object's name, as listed in the API reference config. + page_path + Its page in great-docs' own reference. + + Returns + ------- + str | None + The page great-docs writes for it, or, when quartodoc writes the + reference, its page in quartodoc's inventory: the full name, else + the shortest name ending in it. None if quartodoc doesn't document + it. + """ + if not self._uses_quartodoc: + return f"reference/{page_path}.html" + uris = self._quartodoc_uris + package = self._config.quartodoc.get("package") or "" + if f"{package}.{name}" in uris: + return uris[f"{package}.{name}"] + matches = sorted((n for n in uris if n.endswith(f".{name}")), key=len) + return uris[matches[0]] if matches else None + def _refresh_api_reference_config(self) -> None: """ Refresh the API reference sections in _quarto.yml based on current package exports. @@ -11388,6 +11552,12 @@ def _apply_quarto_overrides(self) -> list[str]: config = read_yaml(f) or {} for _, overrides in layers: config = merge_quarto_overrides(config, overrides) + + # A replaced theme keeps great-docs' stylesheet, which its widgets + # need, but just after the base theme so the user's SCSS wins + html = config.get("format", {}).get("html", {}) + if html.get("theme"): + html["theme"] = with_great_docs_scss(html["theme"], position=1) write_quarto_yml(quarto_yml, config) return [name for name, _ in layers] @@ -11801,10 +11971,7 @@ def _update_quarto_config(self) -> None: # We provide a light background container in dark mode via CSS config["format"]["html"]["mermaid"] = {"theme": "default"} - if "great-docs.scss" not in config["format"]["html"]["theme"]: - if isinstance(config["format"]["html"]["theme"], str): - config["format"]["html"]["theme"] = [config["format"]["html"]["theme"]] - config["format"]["html"]["theme"].append("great-docs.scss") + config["format"]["html"]["theme"] = with_great_docs_scss(config["format"]["html"]["theme"]) # User-defined grammars must keep their order and survive repeated updates. syntax_definitions = config["format"]["html"].get("syntax-definitions") or [] @@ -13442,33 +13609,36 @@ def _generate_llms_txt(self) -> None: section_title = section.title or section.subtitle or "" section_desc = section.desc or "" - # Add section header as a comment or sub-heading if there are multiple sections - if len(sections) > 1 and section_title: - lines.append(f"#### {section_title}") - if section_desc: - lines.append(f"> {section_desc}") - lines.append("") - - # Add each item in the section + # Add each item in the section that has a page + items = [] for entry in section.contents: if not isinstance(entry, SpecObject): continue # pragma: no cover item_name = entry.name + page_url = self._api_page_url(item_name, entry.page_path) + if page_url is None: + continue # Get description from docstring if available item_desc = self._get_docstring_summary(package_name, item_name) - if site_url: - url = f"{site_url}reference/{entry.page_path}.html" - else: - url = f"reference/{entry.page_path}.html" + url = f"{site_url}{page_url}" # Format the line if item_desc: - lines.append(f"- [{item_name}]({url}): {item_desc}") + items.append(f"- [{item_name}]({url}): {item_desc}") else: - lines.append(f"- [{item_name}]({url})") + items.append(f"- [{item_name}]({url})") + if not items: + continue + # Add section header as a comment or sub-heading if there are multiple sections + if len(sections) > 1 and section_title: + lines.append(f"#### {section_title}") + if section_desc: + lines.append(f"> {section_desc}") + lines.append("") + lines.extend(items) lines.append("") # Write the llms.txt file @@ -15389,7 +15559,13 @@ def _prepare_for_freeze(self) -> None: pass # Step 14: Generate API reference - if self._has_api_reference: + if self._uses_quartodoc: + try: + with redirect_stdout(devnull): + self._build_quartodoc() + except Exception: + pass + elif self._has_api_reference: try: from great_docs._apiref.api_reference import APIReference @@ -16092,7 +16268,22 @@ class Result: # ── Step 14: Generate API reference ──────────────────────── step += 1 log.step_start(step, "Generate API reference") - if self._has_api_reference: + claims = None + if self._uses_quartodoc: + ref = None + build_env = self._get_quarto_env() + for p in build_env.get("PYTHONPATH", "").split(os.pathsep): + if p and p not in sys.path: + sys.path.insert(0, p) # pragma: no cover + try: + with _quiet_prints(): + claims = self._build_quartodoc() + log.step_done("API reference generated with quartodoc") + except Exception as e: + log.step_fail(f"quartodoc build failed: {e}") + log.footer() + sys.exit(1) + elif self._has_api_reference: build_env = self._get_quarto_env() extra_paths = build_env.get("PYTHONPATH", "").split(os.pathsep) for p in extra_paths: @@ -16151,7 +16342,7 @@ class Result: self.build_dir, self._config, self._detect_package_name() or "", - AliasClaims.make(ref.items) if ref is not None else AliasClaims(), + claims or (AliasClaims.make(ref.items) if ref is not None else AliasClaims()), ) for note in interlinks_notes: log.detail(note) diff --git a/pyproject.toml b/pyproject.toml index 049bc1166..889fa1ee8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -52,6 +52,9 @@ svg = [ mcp = [ "mcp>=1.0.0", ] +quartodoc = [ + "quartopydoc>=0.13.0", +] marimo = [ "marimo>=0.20.0", # marimo's `export html-wasm` (iframe mode) shells out to uv to resolve the diff --git a/tests/test_config_defaults.py b/tests/test_config_defaults.py index a50d332be..e5fe34af8 100644 --- a/tests/test_config_defaults.py +++ b/tests/test_config_defaults.py @@ -17,7 +17,7 @@ "project_type": "python", "parser": "numpy", # Added after the snapshot: the projects this one links out to. - "interlinks": {"sources": {}, "add_function_parentheses": True}, + "interlinks": {"sources": {}, "aliases": [], "add_function_parentheses": True}, "callable_signatures": {"style": "highlighted", "wrap": "per_parameter"}, "dynamic": True, "jupyter": "python3", @@ -56,6 +56,7 @@ "lang": "en", }, "quarto": {}, + "styles": "all", "show_dates": False, "date_format": "%B %d, %Y", "show_author": True, @@ -69,6 +70,7 @@ "bibliography": [], "csl": None, "reference": [], + "quartodoc": {}, "inline_methods": 5, "logo": {"light": None, "dark": None, "show_title": False}, "favicon": None, diff --git a/tests/test_interlinks.py b/tests/test_interlinks.py index 9e74369d6..067adcda7 100644 --- a/tests/test_interlinks.py +++ b/tests/test_interlinks.py @@ -568,6 +568,16 @@ def test_the_index_resolves_a_name_written_with_a_source_alias(): assert index.resolves("np.missing") is False +def test_the_index_resolves_a_name_written_with_a_local_alias(): + """`import demo as dm` prose writes `dm.Thing`, which wins over a source's `dm`.""" + source = Source(name="numpy", url="https://numpy.org/", aliases=("dm",)) + index = build_index(LOCAL, AliasClaims(), [(source, DEMO)], aliases=("dm",)) + + assert index.prefixes["dm"] == ("demo",) + assert index.resolves("dm.Thing") is True + assert index.resolves("dm.ndarray") is False + + def test_the_index_resolves_nothing_for_an_ambiguous_name(): """The filter refuses it, so a caller asking must be told the same.""" index = build_index(LOCAL, AliasClaims(claimed=(("T", "demo.Thing"), ("T", "demo.go"))), []) diff --git a/tests/test_quarto_overrides.py b/tests/test_quarto_overrides.py index ecfdeee86..257b1ed91 100644 --- a/tests/test_quarto_overrides.py +++ b/tests/test_quarto_overrides.py @@ -65,7 +65,10 @@ def test_quarto_block_merges_into_generated_config(tmp_path): assert docs._apply_quarto_overrides() == ["great-docs.yml `quarto`"] result = _read(docs) assert result["format"]["html"] == { - "theme": {"light": ["flatly", "custom.scss"], "dark": ["darkly", "custom.scss"]}, + "theme": { + "light": ["flatly", "great-docs.scss", "custom.scss"], + "dark": ["darkly", "great-docs.scss", "custom.scss"], + }, "toc-depth": 2, "mainfont": "Source Sans Pro", } @@ -104,3 +107,170 @@ def test_user_overlay_file_must_be_mapping(tmp_path): (tmp_path / "_quarto.user.yml").write_text("- a\n- b\n", encoding="utf-8") with pytest.raises(ValueError, match="must contain a mapping"): docs._apply_quarto_overrides() + + +def test_quarto_theme_override_keeps_great_docs_scss(tmp_path): + docs = _make_docs( + tmp_path, + "quarto:\n format:\n html:\n theme:\n light: [cosmo, a.scss]\n dark: cosmo\n", + ) + docs._apply_quarto_overrides() + assert _read(docs)["format"]["html"]["theme"] == { + "light": ["cosmo", "great-docs.scss", "a.scss"], + "dark": ["cosmo", "great-docs.scss"], + } + + +@pytest.mark.parametrize( + "theme, position, expected", + [ + ("flatly", None, ["flatly", "great-docs.scss"]), + (["flatly", "a.scss"], None, ["flatly", "a.scss", "great-docs.scss"]), + (["flatly", "a.scss"], 1, ["flatly", "great-docs.scss", "a.scss"]), + (["flatly", "great-docs.scss"], 1, ["flatly", "great-docs.scss"]), + ({"light": "flatly", "dark": ["darkly"]}, None, {"light": ["flatly", "great-docs.scss"], "dark": ["darkly", "great-docs.scss"]}), + ], +) +def test_with_great_docs_scss(theme, position, expected): + from great_docs._utils import with_great_docs_scss + + assert with_great_docs_scss(theme, position) == expected + + +# --- quartodoc --------------------------------------------------------------- + +QUARTODOC_YML = ( + "quartodoc:\n" + " style: pkgdown\n" + " sections:\n" + " - title: Greetings\n" + " desc: Ways to say hello\n" + " contents:\n" + " - hello\n" +) + + +def _make_quartodoc_docs(tmp_path: Path, gd_yml: str = QUARTODOC_YML) -> GreatDocs: + pkg = tmp_path / "mypkg" + pkg.mkdir() + (pkg / "__init__.py").write_text( + '"""Demo."""\n\n__all__ = ["hello"]\n\n\ndef hello(name: str) -> str:\n' + ' """Say hello.\n\n Parameters\n ----------\n' + ' name\n Who to greet.\n """\n return name\n', + encoding="utf-8", + ) + docs = _make_docs(tmp_path, gd_yml) + config = { + "project": {"type": "website"}, + "website": {"navbar": {"left": []}, "sidebar": []}, + "format": {"html": {"theme": "flatly"}}, + "api-reference": {"package": "mypkg", "dir": "reference", "sections": []}, + } + write_quarto_yml(docs.build_dir / "_quarto.yml", config) + return docs + + +def test_add_quartodoc_config(tmp_path): + docs = _make_quartodoc_docs(tmp_path, QUARTODOC_YML + " dir: api\n") + docs._add_quartodoc_config() + + assert docs._uses_quartodoc + qd = _read(docs)["quartodoc"] + assert qd["package"] == "mypkg" + assert qd["dir"] == "api" + assert qd["sidebar"] == {"file": "_quartodoc-sidebar.yml", "id": "reference"} + assert qd["sections"][0]["title"] == "Greetings" + + +def test_build_quartodoc(tmp_path, monkeypatch): + pytest.importorskip("quartodoc") + docs = _make_quartodoc_docs(tmp_path, QUARTODOC_YML + " dir: api\n") + config = _read(docs) + config["website"]["navbar"]["left"] = [{"text": "Reference", "href": "reference/index.qmd"}] + config["website"]["sidebar"] = [{"id": "reference", "contents": ["reference/index.qmd"]}] + write_quarto_yml(docs.build_dir / "_quarto.yml", config) + docs._add_quartodoc_config() + monkeypatch.chdir(docs.build_dir) + monkeypatch.syspath_prepend(str(tmp_path)) + claims = docs._build_quartodoc() + + assert "Say hello." in (docs.build_dir / "api" / "hello.qmd").read_text() + result = _read(docs) + assert result["website"]["navbar"]["left"] == [{"text": "Reference", "href": "api/index.qmd"}] + assert result["website"]["sidebar"] == [ + { + "id": "reference", + "contents": ["api/index.qmd", {"section": "Greetings", "contents": ["api/hello.qmd"]}], + } + ] + + # Interlinks and llms.txt use quartodoc's pages + from great_docs._interlinks.sphinx_inventory import decode + + inventory = decode((docs.build_dir / "objects.inv").read_bytes()) + assert any(e.name == "mypkg.hello" for e in inventory.entries) + assert ("hello", "mypkg.hello") in claims.claimed + assert docs._api_page_url("hello", "hello") == docs._quartodoc_uris["mypkg.hello"] + assert docs._api_page_url("hello.missing", "x") is None + assert docs._api_page_url("nothing", "x") is None + + +def test_build_quartodoc_claims_reexported_names(tmp_path, monkeypatch): + """`mypkg.greet.Greeter` is also `mypkg.Greeter`, so a `pkg.` alias reaches it.""" + pytest.importorskip("quartodoc") + docs = _make_quartodoc_docs( + tmp_path, "quartodoc:\n sections:\n - title: All\n contents:\n - greet\n" + ) + pkg = tmp_path / "mypkg" + (pkg / "__init__.py").write_text( + '"""Demo."""\n\nfrom .greet import Greeter\n\n__all__ = ["Greeter"]\n', encoding="utf-8" + ) + (pkg / "greet.py").write_text( + '"""Greetings."""\n\n\nclass Greeter:\n """Greets."""\n\n' + ' def wave(self):\n """Wave."""\n\n\ndef _private():\n """No."""\n', + encoding="utf-8", + ) + config = _read(docs) + config["website"]["sidebar"] = [{"id": "reference", "contents": ["reference/index.qmd"]}] + write_quarto_yml(docs.build_dir / "_quarto.yml", config) + docs._add_quartodoc_config() + monkeypatch.chdir(docs.build_dir) + monkeypatch.syspath_prepend(str(tmp_path)) + claims = docs._build_quartodoc() + + assert ("mypkg.Greeter", "mypkg.greet.Greeter") in claims.claimed + assert ("mypkg.Greeter.wave", "mypkg.greet.Greeter.wave") in claims.claimed + assert ("Greeter.wave", "mypkg.greet.Greeter.wave") in claims.claimed + + +def test_llms_txt_lists_only_what_quartodoc_documents(tmp_path): + docs = _make_quartodoc_docs(tmp_path) + config = _read(docs) + config["api-reference"]["sections"] = [ + {"title": "Documented", "contents": ["hello"]}, + {"title": "Left out", "contents": ["other"]}, + ] + write_quarto_yml(docs.build_dir / "_quarto.yml", config) + docs._uses_quartodoc = True + docs._quartodoc_uris = {"mypkg.hello": "reference/hello.html#mypkg.hello"} + docs._get_package_metadata = lambda: {} + docs._get_docstring_summary = lambda package, name: "" + docs._generate_llms_txt() + + llms = (docs.build_dir / "llms.txt").read_text() + assert "- [hello](reference/hello.html#mypkg.hello)" in llms + assert "other" not in llms + assert "Left out" not in llms + + +@pytest.mark.parametrize("styles, flag", [("all", "true"), ("widgets", "false")]) +def test_styles_sets_the_content_styles_flag(tmp_path, styles, flag): + docs = _make_docs(tmp_path, f"styles: {styles}\n") + docs._prepare_build_directory() + scss = (docs.build_dir / "great-docs.scss").read_text() + assert f"$gd-content-styles: {flag} !default;" in scss + + +def test_styles_must_be_all_or_widgets(tmp_path): + with pytest.raises(ValueError, match="must be"): + _ = _make_docs(tmp_path, "styles: none\n")._config.styles