From f4cb82cd84cd253834e106b069dd7c961602289b Mon Sep 17 00:00:00 2001 From: Stefano David Date: Sun, 7 Jun 2020 18:06:51 +0200 Subject: [PATCH] documentation for proper code-block cross-referencing --- doc/usage/restructuredtext/directives.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 7b9bd2f80..3636de75d 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -571,6 +571,20 @@ __ http://pygments.org/docs/lexers .. versionadded:: 1.3 + In order to cross-reference a code-block using either the + :rst:role:`ref` or the :rst:role:`numref` role, it is necessary + that both :strong:`name` and :strong:`caption` be defined. The + argument of :strong:`name` can then be given to :rst:role:`numref` + to generate the cross-reference. Example:: + + See :numref:`this-py` for an example. + + When using :rst:role:`ref`, it is possible to generate a cross-reference + with only :strong:`name` defined, provided an explicit title is + given. Example:: + + See :ref:`this code snippet ` for an example. + .. rst:directive:option:: dedent: number :type: number