fix: update instructions of rst guideline comment

Author: PLeVasseur

scripts/generate-rst-comment.py

@@ -13,6 +13,7 @@
 
 import json
 import os
+import re
 import sys
 
 # Add the scripts directory to Python path so we can import guideline_utils
@@ -28,6 +29,20 @@
 )
 
 
+def extract_guideline_id(rst_content: str) -> str:
+    """
+    Extract the guideline ID from RST content.
+    
+    Args:
+        rst_content: The generated RST content
+        
+    Returns:
+        The guideline ID (e.g., "gui_abc123XYZ") or empty string if not found
+    """
+    match = re.search(r':id:\s*(gui_[a-zA-Z0-9]+)', rst_content)
+    return match.group(1) if match else ""
+
+
 def generate_comment(rst_content: str, chapter: str) -> str:
     """
     Generate a formatted GitHub comment with instructions and RST content.
@@ -40,17 +55,39 @@ def generate_comment(rst_content: str, chapter: str) -> str:
         Formatted Markdown comment string
     """
     chapter_slug = chapter_to_filename(chapter)
-    target_file = f"src/coding-guidelines/{chapter_slug}.rst"
+    guideline_id = extract_guideline_id(rst_content)
+    
+    # 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"
+        file_instructions = f"""
+### 📁 Target Location
+
+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`."""
+    else:
+        # Fallback for legacy structure (shouldn't happen with new template)
+        target_file = f"src/coding-guidelines/{chapter_slug}.rst"
+        file_instructions = f"""
+### 📁 Target File
+
+Add this guideline to: `{target_file}`"""
 
     comment = f"""## 📋 RST Preview for Coding Guideline
 
 This is an automatically generated preview of your coding guideline in reStructuredText format.
+{file_instructions}
 
-### 📁 Target File
+### 📝 How to Use This
 
-Add this guideline to: `{target_file}`
+**Option A: Automatic (Recommended)**
 
-### 📝 How to Use This
+Once this issue is approved, a maintainer will add the `sign-off: create pr from issue` label, which automatically creates a PR with the guideline file.
+
+**Option B: Manual**
 
 1. **Fork the repository** (if you haven't already) and clone it locally
 2. **Create a new branch** from `main`:
@@ -59,19 +96,27 @@ def generate_comment(rst_content: str, chapter: str) -> str:
    git pull origin main
    git checkout -b guideline/your-descriptive-branch-name
    ```
-3. **Open the target file** `{target_file}` in your editor
-4. **Copy the RST content** below and paste it at the end of the file (before any final directives if present)
-5. **Build locally** to verify the guideline renders correctly:
+3. **Create the guideline file**:
+   ```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`:
+   ```rst
+   .. include:: {guideline_id}.rst.inc
+   ```
+   Keep the includes in alphabetical order by guideline ID.
+6. **Build locally** to verify the guideline renders correctly:
    ```bash
    ./make.py
    ```
-6. **Commit and push** your changes:
+7. **Commit and push** your changes:
    ```bash
-   git add {target_file}
+   git add src/coding-guidelines/{chapter_slug}/
    git commit -m "Add guideline: <your guideline title>"
    git push origin guideline/your-descriptive-branch-name
    ```
-7. **Open a Pull Request** against `main`
+8. **Open a Pull Request** against `main`
 
 <details>
 <summary><strong>📄 Click to expand RST content</strong></summary>