Settings¶

syntax_base_path: str | pathlib.Path¶: Base directory for grammar file paths, relative to the location of conf.py.

syntax_diagrams_text_settings: dict¶: Settings for text diagram renderer. You can override any option from TextRenderSettings by adding it to this dict.

syntax_diagrams_svg_settings: dict¶: Settings for HTML diagram renderer. You can override any option from SvgRenderSettings by adding it to this dict. The only option that you can’t override is css_style, styling should be done via CSS files instead.

syntax_diagrams_svg_latex_settings: dict¶: Settings for LaTeX diagram renderer. You can override any option from SvgRenderSettings by adding it to this dict. The only option that you can’t override is css_style, styling should be done via CSS files instead.

syntax_end_class: 'simple' | 'complex' | None¶: Default value for end-class option.

syntax_mark_root_rule: bool¶: Default value for mark-root-rule option.

syntax_diagrams: bool¶: Default value for diagrams option.

syntax_cc_to_dash: bool¶: Default value for cc-to-dash option.

syntax_lexer_rules: bool¶: Default value for lexer-rules option.

syntax_parser_rules: bool¶: Default value for parser-rules option.

syntax_fragments: bool¶: Default value for fragments option.

syntax_undocumented: bool¶: Default value for undocumented option.

syntax_honor_sections: bool¶: Default value for honor-sections option.

syntax_bison_c_char_literals: bool¶: Default value for honor-sections option.

syntax_grouping: 'mixed' | 'lexer-first' | 'parser-first'¶: Default value for grouping option.

syntax_ordering: 'by-source' | 'by-name'¶: Default value for ordering option.

syntax_literal_rendering: 'name' | 'contents' | 'contents-unquoted'¶: Default value for literal-rendering option.

syntax_a4doc_compat_links: bool¶: If set to True, Sphinx Syntax will add additional anchors compatible with naming scheme used in sphinx-a4doc extension.

Styling diagrams¶

Default CSS rules for syntax diagrams try to match your HTML theme by using the currentColor keyword.

If you need to change them, can add syntax-diagrams-ext.css to your _static directory and use it to add additional styles. To completely replace default CSS, use syntax-diagrams.css instead. To replace styles used in LaTeX builds, use syntax-diagrams-latex.css.

For example, this documentation customizes diagrams to look better with Furo’s dark theme:

@media (prefers-color-scheme: dark) {
    body[data-theme="auto"] svg.syntax-diagram path {
        stroke: var(--color-foreground-secondary);
    }
}

body[data-theme="dark"] svg.syntax-diagram path {
    stroke: var(--color-foreground-secondary);
}

svg.syntax-diagram .escape {
    fill: var(--color-api-name);
}

Adjusting fonts used in diagrams¶

Since SVGs can’t grow and shrink dynamically, renderer needs to know dimensions of nodes’ text ahead of time. This makes changing fonts and sizes a bit of a hassle.

You will need to set the appropriate properties via CSS files; in addition to this, you’ll need to update syntax_diagrams_svg_settings and syntax_diagrams_svg_latex_settings by setting correct *_text_measure properties.

See syntax_diagrams.TextMeasure for more info on how to do this.