What is the difference between code directives and code in ReST?

Question

In each renderer that I tried, code and code-block seem to have the same result: a code block. Both generate the same html - including the classes and tag type (using, I think, docutils?):

 <pre class="code [language] literal-block"> 

So what's the difference? Why do we have both? Are there any visualization tools that make them different? Is there a semantic difference?

Answer 1

code is a reStructuredText directive. code-block is a Sphinx directive.

code-block has a different set of parameters for the code directive. For instance. :emphasize-lines:

Since you are using Sphinx, I would recommend using the code-block directive.

When using code-block I always get the correct selection. When using code I sometimes get colors, and sometimes just alphabetic code blocks. I have yet to figure out which combinations of settings in conf.py that predictably generate color output.

The code directive has the advantage that the document can be used both in the Sphinx document tree and in the stand-alone reStructuredText document.