refactor: render each guideline as a standalone page (#385)

Author: PLeVasseur

builder/build_cli.py

@@ -284,15 +284,18 @@ def main(root):
     )
     args = parser.parse_args()
 
+    debug = args.debug or args.verbose
+    builder = "linkcheck" if args.check_links else "xml" if args.xml else "html"
+
     if args.update_spec_lock_file:
         update_spec_lockfile(SPEC_CHECKSUM_URL, root / "src" / SPEC_LOCKFILE)
 
     build_docs(
         root,
-        "xml" if args.xml else "html",
+        builder,
         args.clear,
         args.serve,
-        args.debug,
+        debug,
         args.offline,
         not args.ignore_spec_lock_diff,
         args.validate_urls,

exts/coding_guidelines/write_guidelines_ids.py

@@ -52,6 +52,13 @@ def write_guidelines_ids(app):
     # List to track guidelines with missing elements
     incomplete_guidelines = []
 
+    def resolve_document_key(docname: str) -> str:
+        parts = docname.split("/")
+        if len(parts) >= 3 and parts[0] == "coding-guidelines":
+            if parts[2].startswith("gui_"):
+                return "/".join([parts[0], parts[1], "index"])
+        return docname
+
     # Process all guidelines
     for need_id, need in all_needs.items():
         if need["type"] == "guideline":
@@ -138,8 +145,9 @@ def write_guidelines_ids(app):
                     }
                 )
 
-            # Add this guideline to the document
-            documents_data[docname]["guidelines"].append(guideline_data)
+            # Add this guideline to the document (group by chapter index when applicable)
+            document_key = resolve_document_key(docname)
+            documents_data[document_key]["guidelines"].append(guideline_data)
 
     # Prepare the final structure for JSON
     documents = []

scripts/common/guideline_pages.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+import re
+
+GUIDELINE_FILE_HEADER = """\
+.. SPDX-License-Identifier: MIT OR Apache-2.0
+   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+.. default-domain:: coding-guidelines
+
+"""
+
+GUIDELINE_TITLE_PATTERN = re.compile(
+    r"^\s*\.\.\s+guideline::\s*(.*?)\s*$",
+    re.MULTILINE,
+)
+
+
+def extract_guideline_title(content: str) -> str:
+    """
+    Extract the guideline title from the guideline directive.
+
+    Args:
+        content: RST content containing a guideline directive
+
+    Returns:
+        Guideline title or empty string if not found
+    """
+    match = GUIDELINE_TITLE_PATTERN.search(content)
+    return match.group(1).strip() if match else ""
+
+
+def build_guideline_page_content(title: str, guideline_body: str) -> str:
+    """
+    Build the full guideline page content.
+
+    Args:
+        title: Guideline title to use for the page heading
+        guideline_body: Guideline directive content (without the file header)
+
+    Returns:
+        Full guideline page content as a string
+    """
+    body = guideline_body.strip()
+    underline = "=" * len(title)
+    return "\n".join(
+        [
+            GUIDELINE_FILE_HEADER.rstrip(),
+            "",
+            title,
+            underline,
+            "",
+            body,
+            "",
+        ]
+    )

scripts/common/guideline_templates.py

@@ -6,6 +6,7 @@
 import re
 import string
 from textwrap import dedent, indent
+from typing import Optional
 
 # Configuration
 CHARS = string.ascii_letters + string.digits
@@ -252,7 +253,7 @@ def guideline_rst_template(
     rationale: str,
     non_compliant_examples: list,  # List of (prose, code) tuples
     compliant_examples: list,  # List of (prose, code) tuples
-    bibliography_entries: list = None,  # List of (key, author, title, url) tuples
+    bibliography_entries: Optional[list] = None,  # List of (key, author, title, url) tuples
 ) -> str:
     """
     Generate a .rst guideline entry from field values.
@@ -310,7 +311,7 @@ def norm(value: str) -> str:
 
     # Generate bibliography block if entries provided
     bibliography_block = ""
-    if bibliography_entries:
+    if bibliography_entries is not None and bibliography_entries:
         bibliography_id = generate_id("bib")
         bibliography_block = generate_bibliography_block(
             bibliography_id,

scripts/extract_rust_examples.py

@@ -11,7 +11,7 @@
 3. Generates a test crate with all examples as doc tests
 4. Runs the tests and reports results
 
-Supports both monolithic chapter files (*.rst) and per-guideline files (*.rst.inc).
+Supports monolithic chapter files and per-guideline files (*.rst).
 
 Configuration is loaded from src/rust_examples_config.toml for default values.
 
@@ -163,10 +163,10 @@ class RustExamplesConfig:
     """Configuration loaded from rust_examples_config.toml"""
 
     def __init__(self):
-        self.edition = None
-        self.channel = None
-        self.version = None
-        self.version_mismatch_threshold = None
+        self.edition: str = ""
+        self.channel: str = ""
+        self.version: str = ""
+        self.version_mismatch_threshold: int = 0
         # Miri settings
         self.miri_require_for_unsafe = True
         self.miri_timeout = 60
@@ -232,7 +232,7 @@ def load(cls, config_path: Path) -> "RustExamplesConfig":
         return config
 
     @classmethod
-    def find_and_load(cls, search_paths: List[Path] = None) -> "RustExamplesConfig":
+    def find_and_load(cls, search_paths: Optional[List[Path]] = None) -> "RustExamplesConfig":
         """
         Find and load configuration from standard locations.
         
@@ -444,7 +444,7 @@ def extract_rust_examples_from_file(
     - Legacy code-block:: rust directives (for backwards compatibility during migration)
     
     Args:
-        file_path: Path to the RST file (supports .rst and .rst.inc)
+        file_path: Path to the RST file
         config: Configuration with default values
         
     Returns:
@@ -509,8 +509,8 @@ def extract_rust_examples_from_file(
         # Note: min_version should only be set if explicitly specified in the example
         # config.version is the reference toolchain version, not a requirement for all examples
         min_version = options.get('version') or options.get('min-version') or None
-        channel = options.get('channel', config.channel)
-        edition = options.get('edition', config.edition)
+        channel = options.get('channel') or config.channel
+        edition = options.get('edition') or config.edition
 
         # Find parent context
         parent_type, parent_id, guideline_id = find_parent_context(content, start)
@@ -586,19 +586,16 @@ def find_rst_files(src_dir: Path) -> List[Path]:
     """
     Find all RST files in the source directory.
     
-    Searches for both:
-    - *.rst files (chapter index files, monolithic chapter files)
-    - *.rst.inc files (per-guideline include files)
+    Searches for:
+    - *.rst files (chapter index files, monolithic chapter files, per-guideline files)
     
     Args:
         src_dir: Directory to search
         
     Returns:
         List of Path objects for all RST files found
     """
-    rst_files = list(src_dir.glob("**/*.rst"))
-    rst_inc_files = list(src_dir.glob("**/*.rst.inc"))
-    return rst_files + rst_inc_files
+    return list(src_dir.glob("**/*.rst"))
 
 
 def extract_all_examples(

scripts/fls_audit.py

@@ -413,7 +413,6 @@ def scan_guideline_references(
 ) -> dict[str, list[dict[str, str]]]:
     fls_to_guidelines: dict[str, list[dict[str, str]]] = {}
     file_paths = set(src_dir.rglob("*.rst"))
-    file_paths.update(src_dir.rglob("*.rst.inc"))
     for path in sorted(file_paths):
         collect_guidelines_from_file(path, repo_root, fls_to_guidelines)
     return fls_to_guidelines
@@ -535,7 +534,6 @@ def build_guideline_text_index(
 ) -> dict[str, dict[str, Any]]:
     index: dict[str, dict[str, Any]] = {}
     file_paths = set((repo_root / "src").rglob("*.rst"))
-    file_paths.update((repo_root / "src").rglob("*.rst.inc"))
 
     current_id: str | None = None
     current_title = ""

scripts/generate-rst-comment.py

@@ -23,6 +23,10 @@
 from dataclasses import dataclass, field
 from typing import List, Set, Tuple
 
+from scripts.common.guideline_pages import (
+    build_guideline_page_content,
+    extract_guideline_title,
+)
 from scripts.common.guideline_templates import parse_bibliography_entries
 from scripts.guideline_utils import (
     chapter_to_filename,
@@ -34,13 +38,6 @@
     normalize_md,
 )
 
-# SPDX header to prepend to guideline files
-GUIDELINE_FILE_HEADER = """\
-.. SPDX-License-Identifier: MIT OR Apache-2.0
-   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
-
-"""
-
 
 @dataclass
 class CodeTestResult:
@@ -138,9 +135,9 @@ def wrap_in_main(code: str) -> str:
     has_mod = re.search(r'\bmod\b', code)
     has_type = re.search(r'\btype\b', code)
 
-    # If it looks like top-level items, don't wrap
+    # If it looks like top-level items, add a stub main
     if has_functions or has_impl or has_struct or has_enum or has_trait or has_mod or has_type:
-        return code
+        return code + "\n\nfn main() {}"
 
     # Check for use/const/static statements
     has_use = re.search(r'\buse\b', code)
@@ -575,8 +572,8 @@ def generate_comment(
     chapter_slug = chapter_to_filename(chapter)
     guideline_id = extract_guideline_id(rst_content)
 
-    # Prepend the SPDX header to the RST content for display
-    full_rst_content = GUIDELINE_FILE_HEADER + rst_content.strip()
+    page_title = extract_guideline_title(rst_content) or f"Guideline {guideline_id}"
+    full_rst_content = build_guideline_page_content(page_title, rst_content)
 
     # Format test results
     test_results_section = format_test_results(test_results)
@@ -587,34 +584,36 @@ def generate_comment(
     # Determine target path based on whether we have a guideline ID
     if guideline_id:
         target_dir = f"src/coding-guidelines/{chapter_slug}/"
-        target_file = f"{target_dir}{guideline_id}.rst.inc"
+        target_file = f"{target_dir}{guideline_id}.rst"
         chapter_index_file = f"{target_dir}index.rst"
         file_instructions = f"""
 ### 📁 Target Location
 
-Create a new file: `{target_file}`
+Create a new file:
+
+- `{target_file}`
 
-> **Note:** The `.rst.inc` extension prevents Sphinx from auto-discovering the file.
-> It will be included via the chapter's `index.rst`.
+Create the guideline page like this:
 
-We add it to this path, to allow the newly added guideline to appear in the correct chapter.
+```rst
+{full_rst_content}
+```
 
 ### 🗂️ Update Chapter Index
 
-Update `{chapter_index_file}` to include `{guideline_id}.rst.inc`, like so:
+Ensure `{chapter_index_file}` lists guideline pages with a toctree:
+
+```rst
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+   :glob:
 
+   gui_*
 ```
-Chapter Name Here <- chapter heading inside of `{chapter_index_file}`
-=================
-
-.. include:: gui_7y0GAMmtMhch.rst.inc -| existing guidelines
-.. include:: gui_ADHABsmK9FXz.rst.inc  |
-...                                    |
-...                                    |
-.. include:: gui_RHvQj8BHlz9b.rst.inc  |
-.. include:: gui_dCquvqE1csI3.rst.inc -|
-.. include:: {guideline_id}.rst.inc <- your new guideline to add
-```"""
+
+With `:glob:` you do not need to add the new guideline manually.
+"""
     else:
         return "No guideline ID generated, failing!"
 
@@ -632,16 +631,21 @@ def generate_comment(
    git pull origin main
    git checkout -b guideline/your-descriptive-branch-name
    ```
-3. **Create the guideline file**:
+3. **Create the guideline directory**:
    ```bash
    mkdir -p src/coding-guidelines/{chapter_slug}
    ```
-4. **Copy the RST content** below into a new file named `{guideline_id}.rst.inc`
-5. **Update the chapter index** - Add an include directive to `src/coding-guidelines/{chapter_slug}/index.rst`:
+4. **Copy the RST content** below into a new file named `{guideline_id}.rst`
+5. **Ensure the chapter index** `src/coding-guidelines/{chapter_slug}/index.rst` contains the toctree block:
    ```rst
-   .. include:: {guideline_id}.rst.inc
+    .. toctree::
+       :maxdepth: 1
+       :titlesonly:
+       :glob:
+
+       gui_*
    ```
-   Keep the includes in alphabetical order by guideline ID.
+   With `:glob:` you do not need to update the index per guideline.
 6. **Build locally** to verify the guideline renders correctly:
    ```bash
    ./make.py