Skip to content

fix: make duplicate URL behavior check for inconsistency #335

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PLeVasseur merged 2 commits into from
Dec 19, 2025
Merged

fix: make duplicate URL behavior check for inconsistency #335

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
858e7ba
fix: make duplicate URL behavior check for inconsistency
PLeVasseur Dec 19, 2025
fff769b
fix: make errors easier to follow and resolve
PLeVasseur Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 80 additions & 24 deletions docs/bibliography.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,12 @@ The bibliography feature allows guideline authors to include references to exter
Contributors can reference citations within guideline text using the `:cite:` role:

```rst
As documented in :cite:`gui_Abc123XyzQrs:RUST-REF-UNION`, union types have specific safety requirements.
As documented in :cite:`gui_Kx9mPq2nL7Yz:RUST-REF-UNION`, union types have specific safety requirements.
```

**Format:** `:cite:`{guideline_id}:{CITATION-KEY}``

- `guideline_id` is the parent guideline's ID (e.g., `gui_Abc123XyzQrs`)
- `guideline_id` is the parent guideline's ID (e.g., `gui_Kx9mPq2nL7Yz`)
- `CITATION-KEY` is the citation key in UPPERCASE-WITH-HYPHENS format

The `:cite:` role renders as a clickable `[CITATION-KEY]` link that navigates to the bibliography entry.
Expand All @@ -29,23 +29,23 @@ Each guideline can include an optional bibliography section with entries defined

```rst
.. guideline:: Union Field Validity
:id: gui_Abc123XyzQrs
:id: gui_Kx9mPq2nL7Yz
...

As documented in :cite:`gui_Abc123XyzQrs:RUST-REF-UNION`, unions have requirements.
As documented in :cite:`gui_Kx9mPq2nL7Yz:RUST-REF-UNION`, unions have requirements.

.. bibliography::
:id: bib_Abc123XyzQrs
:id: bib_Kx9mPq2nL7Yz
:status: draft

.. list-table::
:header-rows: 0
:widths: auto
:class: bibliography-table

* - :bibentry:`gui_Abc123XyzQrs:RUST-REF-UNION`
* - :bibentry:`gui_Kx9mPq2nL7Yz:RUST-REF-UNION`
- The Rust Reference. "Unions." https://doc.rust-lang.org/reference/items/unions.html
* - :bibentry:`gui_Abc123XyzQrs:CERT-C-INT34`
* - :bibentry:`gui_Kx9mPq2nL7Yz:CERT-C-INT34`
- SEI CERT C Coding Standard. "INT34-C." https://wiki.sei.cmu.edu/confluence/x/ItcxBQ
```

Expand All @@ -55,7 +55,7 @@ The `:bibentry:` role creates an anchor that the `:cite:` role links to, and ren

### 3. Why Namespacing?

The guideline ID prefix (`gui_Abc123XyzQrs:`) is required to avoid conflicts when multiple guidelines use the same citation key (e.g., both guidelines might cite `RUST-REF-UNION`). The prefix ensures each citation anchor is unique across the entire documentation.
The guideline ID prefix (`gui_Kx9mPq2nL7Yz:`) is required to avoid conflicts when multiple guidelines use the same citation key (e.g., both guidelines might cite `RUST-REF-UNION`). The prefix ensures each citation anchor is unique across the entire documentation.

When using `generate_guideline_templates.py`, the guideline ID is automatically included in all `:cite:` and `:bibentry:` roles.

Expand Down Expand Up @@ -83,10 +83,16 @@ Citation keys must follow these rules:

The bibliography validator extension checks:
- URL accessibility (HTTP status)
- Duplicate URLs across guidelines
- URL consistency across guidelines (same URL must use identical citation key and description)
- Citation key format compliance
- Citation references match definitions

**Duplicate URL Consistency:** When the same URL appears in multiple guidelines, all instances must use:
- The same citation key (e.g., all use `RUST-REF-UNION`)
- The same description text (e.g., all use `The Rust Reference. "Unions."`)

This ensures readers see consistent references throughout the documentation.

## Configuration

### conf.py Settings
Expand All @@ -101,8 +107,9 @@ bibliography_url_timeout = 10
# Whether broken URLs should fail the build
bibliography_fail_on_broken = True

# Whether duplicate URLs should fail the build
bibliography_fail_on_duplicates = True
# Whether inconsistent duplicate URLs should fail the build
# (same URL with different citation keys or descriptions)
bibliography_fail_on_inconsistent = True
```

### Build Commands
Expand Down Expand Up @@ -200,35 +207,84 @@ The `guidelines-ids.json` now includes bibliography data. All IDs follow the sam
}
```

## Error Messages
## Error Messages and Build Failures

All bibliography validation errors will **fail the build**. This ensures that invalid citations and mismatched guideline IDs are caught during development and CI.

The validation runs in two places:
1. **During document parsing**: The `:cite:` and `:bibentry:` roles check format and log errors
2. **During consistency check**: The `bibliography_validator` scans all guidelines and raises `BibliographyValidationError` if any errors are found

All error messages include copy-pasteable fixes to help contributors quickly resolve issues.

### Broken URL
```
WARNING: [bibliography_validator] Broken URL in src/gui_Foo.rst:
WARNING: [bibliography_validator] Broken URL in src/gui_Rm4kWp8sN2Qx.rst:
URL: https://example.com/broken
Guideline: gui_Foo
Guideline: gui_Rm4kWp8sN2Qx
Error: HTTP 404
Action: Update or remove this reference
```

### Duplicate URL
### Inconsistent Duplicate URL
```
WARNING: [bibliography_validator] Duplicate URL detected:
ERROR: Inconsistent bibliography entry for URL:
URL: https://doc.rust-lang.org/reference/items/unions.html
Found in: gui_UnionFieldValidity, gui_UnionLayout
Action: Consider if both guidelines need this reference
Canonical entry (from gui_Kx9mPq2nL7Yz):
Citation key: [RUST-REF-UNION]
Description: The Rust Reference. "Unions."
Guidelines with inconsistent entries: gui_Ht5vBn3mJ9Lw, gui_Qp8xZc4kR6Fy

Copy-paste fixes:
In gui_Ht5vBn3mJ9Lw, replace the bibliography entry with:
* - :bibentry:`gui_Ht5vBn3mJ9Lw:RUST-REF-UNION`
- The Rust Reference. "Unions." https://doc.rust-lang.org/reference/items/unions.html

In gui_Qp8xZc4kR6Fy, replace the bibliography entry with:
* - :bibentry:`gui_Qp8xZc4kR6Fy:RUST-REF-UNION`
- The Rust Reference. "Unions." https://doc.rust-lang.org/reference/items/unions.html
```

### Invalid Citation Key
```
ERROR: Invalid citation key format: 'lowercase-key'.
Expected: UPPERCASE-WITH-HYPHENS (e.g., RUST-REF-UNION, CERT-C-INT34)
ERROR: Invalid citation key in :cite: role (coding-guidelines/expressions/gui_Bob7x9KmPq2nL):
Key: CERT-C-int34
Must be UPPERCASE-WITH-HYPHENS (e.g., RUST-REF-UNION)
Copy-paste fix: :cite:`gui_Bob7x9KmPq2nL:CERT-C-INT34`
```

### Invalid Role Format

The error message automatically detects the guideline ID from context and includes it in the suggested fix:

```
ERROR: Invalid :cite: format: "RUST-REF-UNION".
Expected format: :cite:`gui_XxxYyyZzz:CITATION-KEY`
Suggested fix: :cite:`gui_Kx9mPq2nL7Yz:RUST-REF-UNION`
```

```
ERROR: Invalid :bibentry: format: "[RUST-REF-UNION]".
Expected format: :bibentry:`gui_XxxYyyZzz:CITATION-KEY`
Suggested fix: :bibentry:`gui_Kx9mPq2nL7Yz:RUST-REF-UNION`
```

### Guideline ID Mismatch

If the guideline ID in a role doesn't match the current guideline:

```
ERROR: Guideline ID mismatch in :cite: role.
Role uses: gui_Bib7x9KmPq2nL
Current guideline: gui_Bob7x9KmPq2nL
Copy-paste fix: :cite:`gui_Bob7x9KmPq2nL:RUST-REF-UNION`
```

```
ERROR: Invalid :cite: format: "RUST-REF-UNION".
Expected format: :cite:`gui_XxxYyyZzz:CITATION-KEY`
ERROR: Guideline ID mismatch in :bibentry: role.
Role uses: gui_Bib7x9KmPq2nL
Current guideline: gui_Bob7x9KmPq2nL
Copy-paste fix: :bibentry:`gui_Bob7x9KmPq2nL:RUST-REF-UNION`
```

## Migration
Expand All @@ -249,8 +305,8 @@ As documented in [RUST-REF-UNION], ...

**After:**
```rst
As documented in :cite:`gui_YourGuidelineId:RUST-REF-UNION`, ...
As documented in :cite:`gui_Kx9mPq2nL7Yz:RUST-REF-UNION`, ...

* - :bibentry:`gui_YourGuidelineId:RUST-REF-UNION`
* - :bibentry:`gui_Kx9mPq2nL7Yz:RUST-REF-UNION`
- The Rust Reference...
```
2 changes: 2 additions & 0 deletions exts/coding_guidelines/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ class CodingGuidelinesDomain(Domain):
label = "Rust Standard Library"
roles = {
"std": std_role.StdRefRole(),
"cite": citation_roles.CiteRole(),
"bibentry": citation_roles.BibEntryRole(),
}
directives = {}
object_types = {}
Expand Down
Loading