Menu
In every renderer I've tried, code and code-block seem to have the exact same result: a block of code. Both generate the exact same html -- including classes and tag kind (using I think it was docutils?):
<pre class="code [language] literal-block">
So, what's the difference? Why do we have both? Are there any renderers that render them differently? Is there a semantic difference?
962
.. contents is a doctutils directive (the underlying library which defines ReST and associated utilities) and automatically generates a table of contents from headlines within the current topic. .. toctree is a Sphinx-defined directive in which you explicitly list documents whose TOCs will be listed out.
In Sphinx/Docutils, directives have a different meaning. Directives in sphinx-lesson are actually the special case of the generic directive class called admonitions. Directives are used to set off a certain block of text. They can be used as an aside or block (e.g. exercise , instructor-note ).
A Python program is constructed from code blocks. A block is a piece of Python program text that is executed as a unit. The following are blocks: a module, a function body, and a class definition. Each command typed interactively is a block.
code is a reStructuredText directive.
code-block is a Sphinx directive.
The code-block has a different set of options to the codedirective.
E.g. :emphasize-lines:
As you are using Sphinx I would recommend using the code-block directive.
When using code-block I always get the correct highlighting. When using code I sometimes get colors and sometimes just literal code blocks. I have yet to figure out what combinations of setting in conf.py that predictably generates colored output.
The code directive does have the advantage that the document can be used both in a Sphinx document tree and at the same time as a stand-alone reStructuredText document.
157
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
