jbms / sphinx-immaterial

Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system
https://jbms.github.io/sphinx-immaterial/
Other
196 stars 29 forks source link

[theme's graphviz ext] xref attr assumes square brackets #168

Closed 2bndy5 closed 1 year ago

2bndy5 commented 1 year ago

I just found that this theme's graphviz ext will crash when an xref is not enclosed in a set of square brackets.

For example, the following code would work fine with the sphinx graphviz ext:

digraph example {
    subgraph cluster_rf24 {
        tooltip="circuitpython_nrf24l01.rf24 module"
        label="circuitpython_nrf24l01.rf24"
        RF24 [
            href="../core_api/basic_api.html#circuitpython_nrf24l01.rf24.RF24"
            tooltip="RF24 class"
        ]
    }
}

But if I change the subgraph's tooltip and label attrs in favor of the new xref attr:

digraph example {
    subgraph cluster_rf24 {
        xref=":mod:`circuitpython_nrf24l01.rf24`"
        RF24 [
            xref=":class:`circuitpython_nrf24l01.rf24.RF24`"
        ]
    }
}

The dot executable complains about the comma syntax. Below is the code passed to the dot exe at docs' build time:

    subgraph cluster_rf24 {
        label=<circuitpython_nrf24l01.rf24>, href="../core_api/basic_api.html#module-circuitpython_nrf24l01.rf24", tooltip=<circuitpython_nrf24l01.rf24 (Python module)>
        RF24 [
            label=<RF24>, href="../core_api/basic_api.html#circuitpython_nrf24l01.rf24.RF24", tooltip=<circuitpython_nrf24l01.rf24.RF24 (Python class)>
        ]
    }
Problematic src https://github.com/jbms/sphinx-immaterial/blob/a944f278cb7f1066482e59b9a17d3311624cd01e/sphinx_immaterial/graphviz.py#L53-L58

Luckily, the dot syntax delimits by whitespace, so the , (or the older ;) delimiters are optional. See this test in the graphviz playground

2bndy5 commented 1 year ago

The current fix I forgot to post is to use square brackets

        subgraph cluster_rf24 {
            graph [xref=":mod:`circuitpython_nrf24l01.rf24`"]
            RF24 [xref=":class:`~circuitpython_nrf24l01.rf24.RF24`"]
        }