From 0443bb6b58c8b5b9d82b04e068dc185a8a2a624b Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:54:23 -0400 Subject: [PATCH 01/10] Allow for CLI index page --- great_docs/core.py | 227 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 210 insertions(+), 17 deletions(-) diff --git a/great_docs/core.py b/great_docs/core.py index 0cdfb9a7..a8faeeaf 100644 --- a/great_docs/core.py +++ b/great_docs/core.py @@ -4172,19 +4172,45 @@ def _generate_cli_reference_pages(self, cli_info: dict) -> list[str | dict]: generated_files: list[str | dict] = [] generated_paths: list[str] = [] - # Generate main CLI page - main_page = self._generate_cli_command_page(cli_info, is_main=True) - main_path = cli_ref_dir / "index.qmd" - with open(main_path, "w") as f: - f.write(main_page) - generated_files.append("reference/cli/index.qmd") - generated_paths.append(str(main_path.relative_to(self.project_path))) + entry_name = cli_info.get("entry_point_name") or cli_info["name"] + entry_safe = entry_name.replace("-", "_") + + # Generate the CLI index (landing) page — a listing of all commands, modelled on the + # API reference index page rather than the root command's own --help dump. + index_page = self._generate_cli_index_page(cli_info, entry_safe) + index_path = cli_ref_dir / "index.qmd" + with open(index_path, "w") as f: + f.write(index_page) + # Label the index entry explicitly (mirrors the "API Index" link) so it reads distinctly + # from the enclosing "CLI Reference" sidebar section title. + from ._translations import get_translation + + cli_index_label = get_translation("cli_index", self._config.language) + generated_files.append({"text": cli_index_label, "href": "reference/cli/index.qmd"}) + generated_paths.append(str(index_path.relative_to(self.project_path))) + + # Generate the root command page (global options, usage, full --help) on its own page so + # the index can stay a pure listing. + root_page = self._generate_cli_command_page(cli_info, is_main=True) + root_path = cli_ref_dir / f"{entry_safe}.qmd" + with open(root_path, "w") as f: + f.write(root_page) + generated_files.append(f"reference/cli/{entry_safe}.qmd") + generated_paths.append(str(root_path.relative_to(self.project_path))) # Generate pages for subcommands - generated_files.extend( - self._generate_subcommand_pages(cli_info, cli_ref_dir, _paths=generated_paths) + subcommand_items = self._generate_subcommand_pages( + cli_info, cli_ref_dir, _paths=generated_paths ) + # When explicit sections are configured, order the flat top-level command entries to + # match the index sections (group entries keep their relative order at the end). + if self._config.cli_sections: + subcommand_items = self._order_cli_sidebar_items( + subcommand_items, self._config.cli_sections + ) + generated_files.extend(subcommand_items) + # Print grouped summary if generated_paths: print("Generating CLI reference .qmd files:") @@ -4193,6 +4219,117 @@ def _generate_cli_reference_pages(self, cli_info: dict) -> list[str | dict]: return generated_files + def _generate_cli_index_page(self, cli_info: dict, entry_safe: str) -> str: + """ + Generate the CLI reference index (landing) page. + + Models the API reference index page: an optional intro paragraph followed by one or more + ``## Section {.doc-group}`` blocks, each a definition list of command links with their + short help. Sections come from ``cli.sections`` in great-docs.yml when configured; + otherwise commands are auto-grouped (leaf commands first, in code order, then one section + per command group). + + Parameters + ---------- + cli_info + The root command info dict (from `_extract_click_command`). + entry_safe + The filesystem-safe name of the entry point (used to link the root command page). + + Returns + ------- + str + Quarto markdown content for ``reference/cli/index.qmd``. + """ + from ._translations import get_translation + + lang = self._config.language + title = self._config.cli_title or get_translation("cli_reference", lang) + + lines: list[str] = [] + + # --- Front matter (mirrors the API reference index) --- + lines.append("---") + lines.append(f'title: "{title}"') + lines.append("body-classes: doc-reference doc-cli-reference") + lines.append("sidebar: cli-reference") + lines.append("page-navigation: false") + lines.append("html-table-processing: none") + lines.append("---") + lines.append("") + + # No body `# {title}` heading: the frontmatter title provides the page title block (as on + # the API reference index), which keeps the `## {.doc-group}` sections at level 2. + + # --- Intro paragraph --- + if self._config.cli_desc: + lines.append("::: {.doc-description}") + lines.append(self._config.cli_desc.strip()) + lines.append(":::") + lines.append("") + + entry_name = cli_info.get("entry_point_name") or cli_info["name"] + top_commands = [c for c in cli_info.get("commands", []) if not c.get("hidden")] + by_name = {c["name"]: c for c in top_commands} + + def emit_entry(cmd: dict, href: str) -> None: + label = "doc-label-cli-group" if cmd.get("is_group") else "doc-label-cli" + name = cmd["name"] + short = (cmd.get("short_help") or "").strip() + lines.append(f"[{name}]({href}){{.doc-function .doc-label .{label}}}") + lines.append(f": {short}" if short else ":  ") + lines.append("") + + def emit_section(section_title: str, section_desc: str | None = None) -> None: + lines.append(f"## {section_title} {{.doc-group}}") + lines.append("") + if section_desc: + lines.append("::: {.doc-description}") + lines.append(section_desc.strip()) + lines.append(":::") + lines.append("") + + # --- Root command link (global options / usage live one click away) --- + root_short = (cli_info.get("short_help") or "").strip() + lines.append( + f"[{entry_name}]({entry_safe}.qmd){{.doc-function .doc-label .doc-label-cli-group}}" + ) + lines.append(f": {root_short}" if root_short else ":  ") + lines.append("") + + cli_sections = self._config.cli_sections + if cli_sections: + # Author-controlled sections: list exactly the named top-level commands, in order. + for section in cli_sections: + emit_section(section.get("title", ""), section.get("desc")) + for cmd_name in section.get("contents", []): + cmd = by_name.get(cmd_name) + if not cmd: + continue + emit_entry(cmd, f"{cmd_name.replace('-', '_')}.qmd") + else: + # Auto layout: leaf commands first (code order), then one section per group. + leaf = [c for c in top_commands if not c.get("is_group")] + groups = [c for c in top_commands if c.get("is_group")] + + if leaf: + emit_section(get_translation("cli_commands", lang)) + for cmd in leaf: + emit_entry(cmd, f"{cmd['name'].replace('-', '_')}.qmd") + + for group in groups: + gsafe = group["name"].replace("-", "_") + emit_section(group["name"], (group.get("short_help") or "").strip() or None) + # The group's own overview page, then each subcommand. + emit_entry(group, f"{gsafe}.qmd") + for sub in group.get("commands", []): + if sub.get("hidden"): + continue + ssafe = sub["name"].replace("-", "_") + emit_entry(sub, f"{gsafe}/{ssafe}.qmd") + + return "\n".join(lines) + def _generate_subcommand_pages( self, cmd_info: dict, @@ -4278,7 +4415,7 @@ def _generate_cli_command_page(self, cmd_info: dict, is_main: bool = False) -> s lines.append( f'title: "[{title}]{{.doc-object-name .doc-function .doc-label .{label_class}}}"' ) - lines.append("body-classes: doc-api-page") + lines.append("body-classes: doc-api-page doc-cli-reference") lines.append("sidebar: cli-reference") lines.append("page-navigation: false") lines.append("html-table-processing: none") @@ -4493,6 +4630,47 @@ def _generate_cli_command_page(self, cmd_info: dict, is_main: bool = False) -> s return "\n".join(lines) + @staticmethod + def _order_cli_sidebar_items( + items: list[str | dict], cli_sections: list[dict] + ) -> list[str | dict]: + """ + Reorder flat top-level command entries to match the configured `cli.sections` order. + + String entries (leaf commands) are sorted to follow the order in which their command + names appear across the configured sections; commands not mentioned keep their original + (code) order after the configured ones. Group `{"section": ...}` dicts retain their + relative order and are appended at the end. + + Parameters + ---------- + items + The sidebar items produced by `_generate_subcommand_pages`. + cli_sections + The `cli.sections` config list. + + Returns + ------- + list[str | dict] + The reordered sidebar items. + """ + # Build the desired rank for each "reference/cli/.qmd" path. + rank: dict[str, int] = {} + for section in cli_sections: + for cmd_name in section.get("contents", []): + safe = cmd_name.replace("-", "_") + rank.setdefault(f"reference/cli/{safe}.qmd", len(rank)) + + strings = [i for i in items if isinstance(i, str)] + groups = [i for i in items if not isinstance(i, str)] + + # Configured commands first (in section order); unmentioned ones keep their code order. + base = len(rank) + ordered = sorted( + enumerate(strings), key=lambda iv: (rank.get(iv[1], base + iv[0]),) + ) + return [path for _, path in ordered] + groups + @staticmethod def _count_cli_sidebar_items(items: list) -> int: """Count the total number of .qmd pages in a (possibly nested) sidebar list.""" @@ -4501,7 +4679,11 @@ def _count_cli_sidebar_items(items: list) -> int: if isinstance(item, str): count += 1 elif isinstance(item, dict): - count += GreatDocs._count_cli_sidebar_items(item.get("contents", [])) + if item.get("href"): + # A labeled link entry (e.g. the index link) is a single page. + count += 1 + else: + count += GreatDocs._count_cli_sidebar_items(item.get("contents", [])) return count def _update_sidebar_with_cli(self, cli_files: list[str | dict]) -> None: @@ -4543,10 +4725,15 @@ def _update_sidebar_with_cli(self, cli_files: list[str | dict]) -> None: break if not cli_section_exists: + from ._translations import get_translation + + cli_section_title = self._config.cli_title or get_translation( + "cli_reference", self._config.language + ) # Add CLI section cli_section = { "id": "cli-reference", - "title": "CLI Reference", + "title": cli_section_title, "contents": cli_files, } sidebar.append(cli_section) @@ -10830,15 +11017,21 @@ def _add_api_reference_config(self) -> None: return # Add API reference configuration with sensible defaults - # Use the importable name (actual module name) for the package field - ref_title = self._config.reference_title or "Reference" + # Use the importable name (actual module name) for the package field. + # The reference index *page* title defaults to "API Reference" (consistent with the + # "CLI Reference" / "MCP Reference" index titles). The *navbar* keeps the shorter + # "Reference" umbrella label, since that entry covers the API, CLI, and MCP references + # via the reference switcher (and other code locates it by the literal text "Reference"). + ref_title = self._config.reference_title or "API Reference" + nav_title = self._config.reference_title or "Reference" ref_desc = self._config.reference_desc - # Translate default reference title for i18n + # Translate default titles for i18n if not self._config.reference_title and self._config.language != "en": from ._translations import get_translation # pragma: no cover - ref_title = get_translation("reference", self._config.language) # pragma: no cover + ref_title = get_translation("api_reference", self._config.language) # pragma: no cover + nav_title = get_translation("reference", self._config.language) # pragma: no cover # Configure the API reference api_ref_config = { @@ -10886,7 +11079,7 @@ def _add_api_reference_config(self) -> None: for item in left ) if not has_ref: - left.append({"text": ref_title, "href": "reference/index.qmd"}) + left.append({"text": nav_title, "href": "reference/index.qmd"}) navbar["left"] = left # Add reference sidebar From 8953628926b27a296b4678f5df0151d6b7abe5ee Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:54:37 -0400 Subject: [PATCH 02/10] Add config settings for CLI index pages --- great_docs/config.py | 47 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/great_docs/config.py b/great_docs/config.py index cc774bb8..d57f2235 100644 --- a/great_docs/config.py +++ b/great_docs/config.py @@ -592,6 +592,44 @@ def cli_name(self) -> str | None: """Get the CLI command name.""" return self.get("cli.name") + @property + def cli_title(self) -> str | None: + """Get the custom CLI reference index title, if set. + + Supports `cli: {title: "Custom Title"}` in great-docs.yml. Returns `None` when no custom + title is configured (the caller falls back to a translated default). + """ + return self.get("cli.title") + + @property + def cli_desc(self) -> str | None: + """Get the CLI reference index intro paragraph, if set. + + Supports `cli: {desc: "Intro text..."}` in great-docs.yml. Returns `None` when no + description is configured. + """ + return self.get("cli.desc") + + @property + def cli_sections(self) -> list[dict[str, Any]]: + """Get the explicit CLI reference index sections. + + Mirrors the `reference:` config. Supports a list of section dicts under `cli.sections`:: + + cli: + sections: + - title: Project setup + desc: "..." + contents: [init, config, uninstall] + + Each `contents` entry is a top-level command name (string). Returns an empty list when no + explicit sections are configured (triggering auto-grouping by command group). + """ + val = self.get("cli.sections", []) + if isinstance(val, list): + return val + return [] + @property def mcp_enabled(self) -> bool: """Check if MCP server documentation is enabled.""" @@ -1792,6 +1830,15 @@ def create_default_config() -> str: # enabled: false # Enable CLI documentation (default: false) # module: my_package.cli # Module containing Click commands (auto-detected) # name: cli # Name of the Click command object (auto-detected) +# title: CLI Reference # Optional title for the CLI index page + sidebar section +# desc: >- # Optional intro paragraph shown atop the CLI index page +# Command-line interface for my-package. +# sections: # Optional explicit grouping/ordering for the CLI index page. +# - title: Project setup # When omitted, commands are auto-grouped in code order +# desc: Create and configure a project. +# contents: [init, config] +# - title: Building +# contents: [build, preview] # Changelog (GitHub Releases) # --------------------------- From 9f81a54b0e04e13a5ac2ce87443b477ca8797f8a Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:54:56 -0400 Subject: [PATCH 03/10] Modify titles and styling of CLI index pages --- great_docs/assets/post-render.py | 36 ++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/great_docs/assets/post-render.py b/great_docs/assets/post-render.py index 865569af..009c072c 100644 --- a/great_docs/assets/post-render.py +++ b/great_docs/assets/post-render.py @@ -3362,12 +3362,15 @@ def process_cli_reference_pages(): with open(html_file, "r", encoding="utf-8") as file: content = file.read() - # Add 'cli-title' class to h1.title elements - # This matches the pattern:

- content = content.replace('

', '

') + cmd_name = os.path.basename(html_file).replace(".html", "") + + # Add 'cli-title' class to h1.title elements so command-page titles match the monospaced + # API object-page style. The CLI index is a listing page (like the API reference index), + # so its plain "CLI Reference" title is left unstyled to match the API index title. + if cmd_name != "index": + content = content.replace('

', '

') # Replace breadcrumb with a "CLI / great-docs cmd" title bar label - cmd_name = os.path.basename(html_file).replace(".html", "") _cli_label = _t("cli", "CLI") _bc_pat = r'' if cmd_name != "index": @@ -3382,12 +3385,12 @@ def process_cli_reference_pages(): f"

" ) else: - # CLI index: show "CLI / great-docs" + # CLI index: show "CLI / Index" to mirror the API reference index ("API / Index"). _cli_title_html = ( f'

' f'{_cli_label}' f'/' - f'great-docs' + f'Index' f"

" ) content = re.sub(_bc_pat, _cli_title_html, content, flags=re.DOTALL) @@ -3715,6 +3718,7 @@ def fix_script_paths(): for _idx_label, _idx_path in [ ("homepage", os.path.join("_site", "index.html")), ("reference index", os.path.join("_site", "reference", "index.html")), + ("CLI reference index", os.path.join("_site", "reference", "cli", "index.html")), ]: if os.path.isfile(_idx_path): with open(_idx_path, "r", encoding="utf-8") as f: @@ -3764,20 +3768,22 @@ def inject_sidebar_body_classes(): def style_api_index_sidebar_item(): """ - Apply inline styles to the 'API Index' sidebar link so it visually separates from the monospace - reference entries. + Apply inline styles to the 'API Index' / 'CLI Index' sidebar links so they visually separate + from the monospace reference entries. - Targets the `` whose href ends with 'reference/index.html' and its parent - `
`. + Targets the `` whose href ends with 'reference/index.html' (API index) or + 'reference/cli/index.html' (CLI index) and its parent `
`. """ import re - print("Styling API Index sidebar item...") + print("Styling reference index sidebar items...") count = 0 font = ( ""Open Sans", -apple-system, BlinkMacSystemFont, " ""Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif" ) + # Match the API index link, or the CLI index link (the extra '/cli' segment is optional). + href_pat = r'href="[^"]*reference/(?:cli/)?index\.html"' for html_file in all_html_files: rel_path = os.path.relpath(html_file, "_site") @@ -3787,11 +3793,9 @@ def style_api_index_sidebar_item(): with open(html_file, "r", encoding="utf-8") as f: content = f.read() - # Find the sidebar-item-container div immediately followed by the - # API Index link (href ending in reference/index.html) + # Find the sidebar-item-container div immediately followed by the index link. match = re.search( - r'(
\s*' - r']*href="[^"]*reference/index\.html"[^>]*>)', + r'(
\s*]*' + href_pat + r"[^>]*>)", content, ) if not match: @@ -3818,7 +3822,7 @@ def style_api_index_sidebar_item(): f.write(new_content) count += 1 - print(f"Styled API Index sidebar item in {count} reference HTML files") + print(f"Styled reference index sidebar items in {count} reference HTML files") style_api_index_sidebar_item() From aee34bf6589b180a145034496d20e0a46bc1f442 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:55:13 -0400 Subject: [PATCH 04/10] Add new config for CLI pages --- great-docs.yml | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/great-docs.yml b/great-docs.yml index c6b49382..cb7f761b 100644 --- a/great-docs.yml +++ b/great-docs.yml @@ -305,7 +305,6 @@ reference: contents: - name: GreatDocs members: false - - title: GreatDocs Methods desc: >- Methods for installing dependencies, building the documentation site, launching a live @@ -316,7 +315,6 @@ reference: - GreatDocs.build - GreatDocs.preview - GreatDocs.check_links - - title: Table Preview/Explorer desc: >- Generate styled HTML table previews from any tabular data source with `tbl_preview()`, and @@ -326,10 +324,8 @@ reference: - enable_tbl_preview - disable_tbl_preview - tbl_explorer - - title: Skills - desc: >- - Install, check, and list Agent Skills from the Python API. + desc: Install, check, and list Agent Skills from the Python API. contents: - install_skill - check_skill @@ -341,6 +337,29 @@ cli: enabled: true module: great_docs.cli name: cli + desc: >- + The `great-docs` command-line interface drives the full documentation + workflow: from initializing a project and building the site to checking + links, recording terminal sessions, and publishing to GitHub Pages. + sections: + - title: Project setup + desc: Initialize a project, manage its configuration, and remove Great Docs. + contents: [init, config, uninstall] + - title: Building & previewing + desc: Build the documentation site, preview it locally, and freeze executable content. + contents: [build, preview, freeze] + - title: Analysis & quality + desc: Inspect the project, validate links, and check SEO, prose, and style. + contents: [scan, timings, check-links, seo, lint, proofread] + - title: API tracking + desc: Snapshot the public API and diff it across versions. + contents: [api-snapshot, api-diff] + - title: Publishing & versions + desc: Set up GitHub Pages, manage versioned builds, and generate the changelog. + contents: [setup-github-pages, versions, changelog] + - title: Command groups + desc: Grouped commands for Agent Skills and terminal session recordings. + contents: [skill, termshow] # MCP Server Documentation # ------------------------ From c51b7a7c1fcf53f5260474f2b9056b32cd382f14 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:55:30 -0400 Subject: [PATCH 05/10] Add translations for 'CLI Index' --- great_docs/_translations.py | 54 +++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/great_docs/_translations.py b/great_docs/_translations.py index 24568c70..e7007ce3 100644 --- a/great_docs/_translations.py +++ b/great_docs/_translations.py @@ -1600,6 +1600,60 @@ "ar": "فهرس API", "he": "אינדקס API", }, + "cli_index": { + "en": "CLI Index", + "fr": "Index CLI", + "de": "CLI-Index", + "es": "Índice CLI", + "pt": "Índice da CLI", + "it": "Indice CLI", + "nl": "CLI-index", + "ja": "CLIインデックス", + "ko": "CLI 색인", + "zh-Hans": "CLI 索引", + "zh-Hant": "CLI 索引", + "ru": "Указатель CLI", + "pl": "Indeks CLI", + "tr": "CLI Dizini", + "sv": "CLI-index", + "da": "CLI-indeks", + "nb": "CLI-indeks", + "is": "CLI-vísir", + "fi": "CLI-hakemisto", + "cs": "CLI index", + "ro": "Index CLI", + "el": "Ευρετήριο CLI", + "hi": "CLI अनुक्रमणिका", + "ar": "فهرس CLI", + "he": "אינדקס CLI", + }, + "cli_commands": { + "en": "Commands", + "fr": "Commandes", + "de": "Befehle", + "es": "Comandos", + "pt": "Comandos", + "it": "Comandi", + "nl": "Opdrachten", + "ja": "コマンド", + "ko": "명령어", + "zh-Hans": "命令", + "zh-Hant": "命令", + "ru": "Команды", + "pl": "Polecenia", + "tr": "Komutlar", + "sv": "Kommandon", + "da": "Kommandoer", + "nb": "Kommandoer", + "is": "Skipanir", + "fi": "Komennot", + "cs": "Příkazy", + "ro": "Comenzi", + "el": "Εντολές", + "hi": "कमांड", + "ar": "الأوامر", + "he": "פקודות", + }, "cli": { "en": "CLI", "fr": "CLI", From 84c5a9e33b619e9fd50e56e9f837ebd46b940f6b Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:55:37 -0400 Subject: [PATCH 06/10] Update _versioned_build.py --- great_docs/_versioned_build.py | 75 +++++++++++++++++++--------------- 1 file changed, 41 insertions(+), 34 deletions(-) diff --git a/great_docs/_versioned_build.py b/great_docs/_versioned_build.py index c4606df9..2f102cfc 100644 --- a/great_docs/_versioned_build.py +++ b/great_docs/_versioned_build.py @@ -184,14 +184,15 @@ def _prune_cli_pages(dest_dir: Path, snap: object) -> None: return # Build the set of valid command file stems from the snapshot. - # CliCommandInfo.subcommands holds the actual commands; the group itself - # maps to `index.qmd`. + # CliCommandInfo.subcommands holds the actual commands; the index page maps to `index.qmd` + # and the root command's own page maps to the entry point's safe name. valid_stems: set[str] = {"index"} - valid_names: set[str] = set() + entry_name = getattr(cli_commands, "name", "") or "" + if entry_name: + valid_stems.add(entry_name.replace("-", "_")) for sub in getattr(cli_commands, "subcommands", []): # Click command names use hyphens; file stems use underscores valid_stems.add(sub.name.replace("-", "_")) - valid_names.add(sub.name) # Remove QMD files for commands not present at this version for qmd_file in list(cli_ref_dir.iterdir()): @@ -200,47 +201,53 @@ def _prune_cli_pages(dest_dir: Path, snap: object) -> None: if qmd_file.stem not in valid_stems: qmd_file.unlink() - # Rewrite the index.qmd to remove stale commands from the help text + # Rewrite the index.qmd to remove stale commands from the listing index_qmd = cli_ref_dir / "index.qmd" - if index_qmd.exists() and valid_names: - _rewrite_cli_index(index_qmd, valid_names) + if index_qmd.exists(): + _rewrite_cli_index(index_qmd, valid_stems) # Prune the CLI sidebar in _quarto.yml _prune_quarto_cli_sidebar(dest_dir, valid_stems) -def _rewrite_cli_index(index_qmd: Path, valid_names: set[str]) -> None: - """Remove lines for non-existent commands from the CLI index help block.""" +def _rewrite_cli_index(index_qmd: Path, valid_stems: set[str]) -> None: + """Remove command entries for non-existent commands from the CLI index listing. + + The index is a definition list of ``[name](href){...}`` entries. An entry is kept when the + first path component of its href (e.g. ``init`` from ``init.qmd``, or ``skill`` from + ``skill/install.qmd``) is a valid command stem at this version. Dropping an entry also drops + its ``: description`` line and the trailing blank line. + """ content = index_qmd.read_text(encoding="utf-8") lines = content.split("\n") - new_lines: list[str] = [] - in_commands_block = False + entry_re = re.compile(r"^\[[^\]]+\]\((?P[^)]+)\)\{") - for line in lines: - stripped = line.strip() - - # Detect the "Commands:" header in the help text - if stripped == "Commands:": - in_commands_block = True - new_lines.append(line) - continue - - if in_commands_block: - # End of commands block: blank line or closing fence - if not stripped or stripped.startswith("```") or stripped.startswith(":::"): - in_commands_block = False - new_lines.append(line) - continue - - # Each command line looks like " command-name Description text..." - # Extract the command name (first non-whitespace token) - tokens = stripped.split() - if tokens and tokens[0] in valid_names: - new_lines.append(line) - # Skip lines for commands not in valid_names + new_lines: list[str] = [] + i = 0 + n = len(lines) + while i < n: + match = entry_re.match(lines[i].strip()) + if match: + stem = match.group("href").split("/")[0] + if stem.endswith(".qmd"): + stem = stem[:-4] + elif stem.endswith(".md"): + stem = stem[:-3] + + if stem in valid_stems: + new_lines.append(lines[i]) + i += 1 + else: + # Skip the link line, its ": description" line, and one trailing blank line. + i += 1 + if i < n and lines[i].lstrip().startswith(":"): + i += 1 + if i < n and not lines[i].strip(): + i += 1 continue - new_lines.append(line) + new_lines.append(lines[i]) + i += 1 index_qmd.write_text("\n".join(new_lines), encoding="utf-8") From e7acffc590e47bd7c09b42c881d65aed48a3e528 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:55:51 -0400 Subject: [PATCH 07/10] Modify some styling in CLI index pages --- great_docs/assets/great-docs.scss | 37 ++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/great_docs/assets/great-docs.scss b/great_docs/assets/great-docs.scss index 880641be..ee726c76 100644 --- a/great_docs/assets/great-docs.scss +++ b/great_docs/assets/great-docs.scss @@ -1419,6 +1419,41 @@ a.sidebar-item-text.sidebar-link.text-start > span { padding-bottom: 8px; } +/* CLI reference: present command groups (e.g. SKILL, TERMSHOW) as small uppercase + pills so they read as command groups, distinct from leaf commands. Scoped to the + CLI reference pages via the doc-cli-reference body class. */ +body.doc-cli-reference #quarto-sidebar .sidebar-item-section + > .sidebar-item-container + > .sidebar-item-text + .menu-text { + display: inline-block; + text-transform: uppercase; + font-family: $font-family-monospace; + font-size: 0.7rem; + letter-spacing: 0.04em; + line-height: 1.2; + padding: 0.1rem 0.4rem; + border-radius: 0.25rem; + border: 1px solid $label-cli-group-color; + color: $label-cli-group-color; + background-color: tint-color($label-cli-group-color, 90%); +} + +/* Give each CLI command group a little breathing room above its pill. */ +body.doc-cli-reference #quarto-sidebar .sidebar-item-section { + margin-top: 0.4rem; +} + +/* The first command group follows a plain leaf command (no section + padding-bottom above it), so it needs extra top margin to match the gap that + later groups (e.g. TERMSHOW) get from the preceding group's padding-bottom. */ +body.doc-cli-reference + #quarto-sidebar + li.sidebar-item:not(.sidebar-item-section) + + li.sidebar-item-section { + margin-top: 0.9rem; +} + /* ========================================================================== Floating Sidebar Navigation (desktop only) Transforms #quarto-sidebar into a pinned, independently-scrollable panel @@ -2872,7 +2907,7 @@ html.quarto-dark .gd-badge-deprecated, margin-left: 0; margin-right: 0.6rem; margin-bottom: 0.2rem; - padding-top: 1.25rem; + padding-top: 0.5rem; padding-bottom: 0.6rem; border-bottom: 1px solid rgba(0, 0, 0, 0.06); background: transparent; From c0c64643480628023ee21c56890bf1b6558cde11 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:55:53 -0400 Subject: [PATCH 08/10] Update test_great_docs.py --- tests/test_great_docs.py | 105 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 104 insertions(+), 1 deletion(-) diff --git a/tests/test_great_docs.py b/tests/test_great_docs.py index fd455ed8..78c0b300 100644 --- a/tests/test_great_docs.py +++ b/tests/test_great_docs.py @@ -11656,11 +11656,114 @@ def test_generate_cli_reference_pages_basic(): } result = docs._generate_cli_reference_pages(cli_info) - assert "reference/cli/index.qmd" in result + # The index is now a labeled listing entry (not the root command page). + assert {"text": "CLI Index", "href": "reference/cli/index.qmd"} in result assert (docs.project_path / "reference" / "cli" / "index.qmd").exists() + # The root command page now lives on its own page (entry name -> safe name). + assert "reference/cli/tool.qmd" in result + assert (docs.project_path / "reference" / "cli" / "tool.qmd").exists() assert (docs.project_path / "reference" / "cli" / "build.qmd").exists() +def test_generate_cli_index_page_auto_layout(): + """_generate_cli_index_page auto-groups leaf commands then command groups.""" + with tempfile.TemporaryDirectory() as tmp_dir: + docs = GreatDocs(project_path=tmp_dir) + + cli_info = { + "name": "tool", + "entry_point_name": "tool", + "short_help": "A tool.", + "is_group": True, + "commands": [ + {"name": "build", "short_help": "Build it.", "is_group": False, "commands": []}, + {"name": "init", "short_help": "Init it.", "is_group": False, "commands": []}, + { + "name": "skill", + "short_help": "Manage skills.", + "is_group": True, + "commands": [ + {"name": "install", "short_help": "Install.", "commands": []}, + ], + }, + ], + } + + page = docs._generate_cli_index_page(cli_info, "tool") + + # Front matter mirrors the API reference index, plus the CLI scoping class. + assert "body-classes: doc-reference doc-cli-reference" in page + assert "sidebar: cli-reference" in page + # Root command link is present with the group pill. + assert "[tool](tool.qmd){.doc-function .doc-label .doc-label-cli-group}" in page + # Leaf commands are listed (code order) under the auto "Commands" section. + assert "## Commands {.doc-group}" in page + assert "[build](build.qmd){.doc-function .doc-label .doc-label-cli}" in page + assert page.index("[build]") < page.index("[init]") + # The group gets its own section, with its overview and subcommand links. + assert "## skill {.doc-group}" in page + assert "[skill](skill.qmd){.doc-function .doc-label .doc-label-cli-group}" in page + assert "[install](skill/install.qmd){.doc-function .doc-label .doc-label-cli}" in page + + +def test_generate_cli_index_page_configured_sections(): + """cli.sections drives index section titles, ordering, and intro.""" + with tempfile.TemporaryDirectory() as tmp_dir: + docs = GreatDocs(project_path=tmp_dir) + docs._config._config["cli"] = { + "title": "Command Line", + "desc": "Drive everything from the terminal.", + "sections": [ + {"title": "Building", "desc": "Make the site.", "contents": ["build"]}, + {"title": "Setup", "contents": ["init"]}, + ], + } + + cli_info = { + "name": "tool", + "entry_point_name": "tool", + "short_help": "A tool.", + "is_group": True, + "commands": [ + {"name": "init", "short_help": "Init it.", "is_group": False, "commands": []}, + {"name": "build", "short_help": "Build it.", "is_group": False, "commands": []}, + ], + } + + page = docs._generate_cli_index_page(cli_info, "tool") + + assert 'title: "Command Line"' in page + assert "Drive everything from the terminal." in page + assert "## Building {.doc-group}" in page + assert "Make the site." in page + assert "## Setup {.doc-group}" in page + # Configured order wins: Building (build) appears before Setup (init). + assert page.index("## Building") < page.index("## Setup") + + +def test_order_cli_sidebar_items_honors_sections(): + """_order_cli_sidebar_items reorders flat entries to match cli.sections.""" + items = [ + "reference/cli/init.qmd", + "reference/cli/build.qmd", + "reference/cli/scan.qmd", + {"section": "skill", "contents": ["reference/cli/skill.qmd"]}, + ] + sections = [ + {"title": "Building", "contents": ["build"]}, + {"title": "Setup", "contents": ["init"]}, + ] + ordered = GreatDocs._order_cli_sidebar_items(items, sections) + + # build, then init (configured order); scan keeps code order after; group last. + assert ordered == [ + "reference/cli/build.qmd", + "reference/cli/init.qmd", + "reference/cli/scan.qmd", + {"section": "skill", "contents": ["reference/cli/skill.qmd"]}, + ] + + def test_generate_subcommand_pages_nested(): """_generate_subcommand_pages handles nested command groups.""" with tempfile.TemporaryDirectory() as tmp_dir: From 2038691fe377ff2d346d92d28b52e4aff78d24f5 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:55:55 -0400 Subject: [PATCH 09/10] Update test_synthetic.py --- tests/test_synthetic.py | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/tests/test_synthetic.py b/tests/test_synthetic.py index 3331b197..bfde5b9b 100644 --- a/tests/test_synthetic.py +++ b/tests/test_synthetic.py @@ -604,11 +604,12 @@ def test_L3_cli_sidebar_flat_paths(pkg_name: str, tmp_path: Path): sidebar_items = docs._generate_cli_reference_pages(cli_info) assert len(sidebar_items) >= 1, "No sidebar items generated" - # First item should be the main index page - assert sidebar_items[0] == "reference/cli/index.qmd" + # First item should be the labeled index link + assert isinstance(sidebar_items[0], dict) + assert sidebar_items[0].get("href") == "reference/cli/index.qmd" - # Every item should be a plain path string (no section dicts) - for item in sidebar_items: + # Remaining items should be plain path strings (flat CLI -> no section dicts) + for item in sidebar_items[1:]: assert isinstance(item, str), f"Expected plain path string, got dict: {item}" assert item.startswith("reference/cli/"), ( f"Sidebar path {item!r} does not start with 'reference/cli/'" @@ -636,11 +637,14 @@ def test_L3_cli_sidebar_nested_structure(pkg_name: str, tmp_path: Path): sidebar_items = docs._generate_cli_reference_pages(cli_info) assert len(sidebar_items) >= 2, "Too few sidebar items for a grouped CLI" - # First item should be the main index - assert sidebar_items[0] == "reference/cli/index.qmd" + # First item should be the labeled index link + assert isinstance(sidebar_items[0], dict) + assert sidebar_items[0].get("href") == "reference/cli/index.qmd" - # Collect section dicts from the sidebar items - section_items = [item for item in sidebar_items if isinstance(item, dict)] + # Collect group section dicts (the index link dict has 'href', not 'section') + section_items = [ + item for item in sidebar_items if isinstance(item, dict) and "section" in item + ] assert len(section_items) > 0, ( f"No section dicts found in sidebar items; " f"nested groups should use {{section: ..., contents: [...]}} structure. " From 936949451f477464baba40f5925a2c8a9f39d8d9 Mon Sep 17 00:00:00 2001 From: Richard Iannone Date: Tue, 30 Jun 2026 14:55:58 -0400 Subject: [PATCH 10/10] Update test_versioned_build.py --- tests/test_versioned_build.py | 46 +++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/tests/test_versioned_build.py b/tests/test_versioned_build.py index aa177079..3c337e67 100644 --- a/tests/test_versioned_build.py +++ b/tests/test_versioned_build.py @@ -1419,20 +1419,29 @@ def test_removes_invalid_commands(self, tmp_path: Path): index = tmp_path / "index.qmd" index.write_text( - "---\ntitle: CLI\n---\n\n" - "```\n" - "Commands:\n" - " build Build the docs\n" - " preview Preview the site\n" - " old-cmd Deprecated command\n" - "```\n" - ) - - _rewrite_cli_index(index, {"build", "preview"}) + "---\ntitle: CLI Reference\n---\n\n" + "# CLI Reference\n\n" + "## Commands {.doc-group}\n\n" + "[build](build.qmd){.doc-function .doc-label .doc-label-cli}\n" + ": Build the docs\n\n" + "[preview](preview.qmd){.doc-function .doc-label .doc-label-cli}\n" + ": Preview the site\n\n" + "[old-cmd](old_cmd.qmd){.doc-function .doc-label .doc-label-cli}\n" + ": Deprecated command\n\n" + "## skill {.doc-group}\n\n" + "[install](skill/install.qmd){.doc-function .doc-label .doc-label-cli}\n" + ": Install a skill\n\n" + ) + + # Note: stems use underscores; "skill" group is valid so its subcommand is kept. + _rewrite_cli_index(index, {"index", "build", "preview", "skill"}) content = index.read_text() - assert "build" in content - assert "preview" in content - assert "old-cmd" not in content + assert "[build](build.qmd)" in content + assert "[preview](preview.qmd)" in content + assert "[old-cmd]" not in content + assert "Deprecated command" not in content + # Nested subcommand of a surviving group is retained. + assert "[install](skill/install.qmd)" in content class TestPruneQuartoCliSidebar: @@ -3471,9 +3480,14 @@ def test_prunes_and_rewrites_index(self, tmp_path: Path): cli_dir = tmp_path / "reference" / "cli" cli_dir.mkdir(parents=True) (cli_dir / "index.qmd").write_text( - "---\ntitle: CLI\n---\n\n```\nUsage: gd [OPTIONS]\n\n" - "Commands:\n build Build docs\n serve Serve docs\n" - " old-cmd Old command\n```\n" + "---\ntitle: CLI Reference\n---\n\n# CLI Reference\n\n" + "## Commands {.doc-group}\n\n" + "[build](build.qmd){.doc-function .doc-label .doc-label-cli}\n" + ": Build docs\n\n" + "[serve](serve.qmd){.doc-function .doc-label .doc-label-cli}\n" + ": Serve docs\n\n" + "[old-cmd](old_cmd.qmd){.doc-function .doc-label .doc-label-cli}\n" + ": Old command\n\n" ) (cli_dir / "build.qmd").write_text("Build cmd") (cli_dir / "serve.qmd").write_text("Serve cmd")