[Documentation] mention the existence of the RST `.. code::` directive

[jakkdl]

Is your feature request related to a problem? Please describe. I just spent way too long being confused by what the difference between .. code:: and .. code-block:: were, which in large part was caused by .. code:: not being mentioned at all in the sphinx documentation. I'd expect some, if not all, of these sections to mention it: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-directives https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block

It is only indirectly documented by https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directives saying

As previously discussed, a directive is a generic block of explicit markup. While Docutils provides a number of directives, Sphinx provides many more and uses directives as one of the primary extension mechanisms.

and that making the reader independently hunt down a link to the docutils documentation for directives - where it can finally be found: https://docutils.sourceforge.io/docs/ref/rst/directives.html#code

Soooo... what is the difference in terms of sphinx docs? As far as I can tell it's solely that .. code:: does not support options such as :linenos:

Describe the solution you'd like Mention it existing, but that it is strictly inferior and in general not recommended.

Describe alternatives you've considered Make .. code:: also support options, and elevate it to being a proper alias for .. code-block:: as with .. sourcecode::. But maybe that is problematic because it breaks the RST spec or something?

Additional context Encountered while working on https://github.com/python-trio/trio/pull/2968

[picnixz]

There is a historical reason why we have these two directives but long-story short, .. code is a docutils directive (that we support as a pure docutils) and .. code-block is a Sphinx one (which is an improvement of the latter).

We don't really want to mention the two of them because what is generally needed is the code-block directive and not the code directive. If we were to mention it, users would maybe try to use the ..code directive.

There was a very old issue (https://github.com/sphinx-doc/sphinx/issues/2155) that I recently closed where it was debated whether to keep code synced with the docutils one or not. One maintainer personnally preferred merging these two together but eventually made a PR where code and code-block are distinct. While I also share this opinion, having distinct code directives might be useful for extensions that assume that the code directive is compatible with docutils and has minimal processing in their run method, so I would not change the behaviour.

Nevertheless, what we can do is mention the code directive but stress that code-block is better for most usage.