I should document the rst-example directive (& its myst-example alias for .md doc sources).
I keep seeing possible use cases for this directive in user projects/examples. But there is no documentation to make users aware that the sphinx_immaterial.theme_result extension exists and what it provides.
For those passing by, the rst-example directive works by taking RST code as content and rendering an RST code block followed by a rendition of the RST code using the given sphinx builder (HTML-based is preferred/tested). This is used liberally throughout our docs and avoids the common copy-and-paste that doc authors would normally have to do to achieve a similar result.
I should document the
rst-exampledirective (& itsmyst-examplealias for .md doc sources).I keep seeing possible use cases for this directive in user projects/examples. But there is no documentation to make users aware that the
sphinx_immaterial.theme_resultextension exists and what it provides.For those passing by, the
rst-exampledirective works by taking RST code as content and rendering an RST code block followed by a rendition of the RST code using the given sphinx builder (HTML-based is preferred/tested). This is used liberally throughout our docs and avoids the common copy-and-paste that doc authors would normally have to do to achieve a similar result.