jbms
production lists rendered incorrectly
I noticed this a long time ago, but keep forgetting to file this issue.
An erroneous example can be seen in our hosted docs
I think the expected behavior is something that resembles a typical code-block but with cross-referencing links in certain parts of the code. I generally don't use the productionlist directive, but I figured I should say something.
The directive's docs are at the Sphinx docs
An expected behavior can be observed from the attached simple project (uses furo theme) prod-list-proper.zip
The problem seems to be related to misinterpreting the backticks ` within the directive's content.
Yeah, I'm not sure what is going on. I noticed this issue when first putting together this theme, but since I have no use for productionlist I didn't bother to look into it more.
I have a feeling its related to CSS in upstream not compensated for production lists' style(s) or misunderstanding the code element's context.
Peeked at the visit_productionlist() in Sphinx, and it doesn't enclose the literal block in a <code> element. Not sure if this violates HTML5 specs, but I think this should be elevated in sphinx before we address it here, which will likely involve another monkeypatch to ~(or rewrite of)~ the visitor.
With an added <code> element, the productionlist directive renders in a more expected way, but the backticks within the block are treated as references and triggering warnings in the build log since there's no definition to reference. According to the Sphinx docs (which is a bit vague in its terminology), the references are supposed to be defined by other production lists (see the python docs from which the the sample snippet in OP is taken from).
preliminary test with patched visitor
A modified production list taken from graphviz docs:
We could use the :token: role to reference grammar in dot syntax using this production list 😉
All in all, I think this directive is rather specific in usage but nonetheless interesting. I'm still exploring...
doesn't enclose the literal block in a <code> element. Not sure if this violates HTML5 specs
I've been researching, and it doesn't look like the HTML5 specs require a code element within a pre element (specs about the pre tag seem to be inherited from the original HTML specs). So, I don't think this is worthy of Sphinx attention; such a change may break CSS with other themes about production lists. Rather the problem (in the OP) is more specific to mkdocs-material's CSS/JS which expect there to always be a code element within a pre element. Nested code elements (for inline references) haven't been a problem during my tests.
I've pushed a patch to a new branch and will submit a PR for review.