Proposed rule
Prefer {index} directives over {index} roles in section headings.
Problem
Using the index role inline in a heading makes the title hard to read in the source:
# {index}`Polars <single: Polars>`
Preferred style
Use a plain heading followed by one or more index directives:
# Polars
```{index} single: Polars
```
Rationale
- The heading text stays clean and readable in the
.md source
- The index entries are still generated identically in the built output
- Easier to maintain when multiple index entries are needed (just add more directives)
This came up during review of QuantEcon/lecture-python-programming#408.
Proposed rule
Prefer
{index}directives over{index}roles in section headings.Problem
Using the index role inline in a heading makes the title hard to read in the source:
# {index}`Polars <single: Polars>`Preferred style
Use a plain heading followed by one or more index directives:
Rationale
.mdsourceThis came up during review of QuantEcon/lecture-python-programming#408.