refs #1742: :name: option is provided for toctree, code-block and literalinclude dirctives.

CHANGES

@@ -79,7 +79,9 @@ Features added
 
 * #1227: Add `html_scaled_image_link` config option to conf.py, to control
   scaled image link.
-* #1700: Add `:caption:` option for `toctree`.
+* #1700: Add ``:caption:`` option for :rst:dir:`toctree`.
+* #1742: ``:name:`` option is provided for :rst:dir:`toctree`, :rst:dir:`code-block` and
+  :rst:dir:`literalinclude` dirctives.
 
 Bugs fixed
 ----------

doc/markup/code.rst

@@ -214,23 +214,26 @@ Includes
       The ``lineno-match`` option.
 
 
-Showing a file name
+Caption and name
-^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^
 
 .. versionadded:: 1.3
 
-A ``caption`` option can be given to show that name before the code block.  For
+A ``caption`` option can be given to show that name before the code block.
-example::
+A ``name`` option can be provided implicit target name that can be referenced
+by using :rst:role:`ref`.
+For example::
 
    .. code-block:: python
       :caption: this.py
+      :name: this-py
 
       print 'Explicit is better than implicit.'
 
 
-:rst:dir:`literalinclude` also supports the ``caption`` option, with the
+:rst:dir:`literalinclude` also supports the ``caption`` and ``name`` option.
-additional feature that if you leave the value empty, the shown filename will be
+``caption`` has a additional feature that if you leave the value empty, the shown
-exactly the one given as an argument.
+filename will be exactly the one given as an argument.
 
 
 Dedent

doc/markup/toctree.rst

@@ -85,10 +85,13 @@ tables of contents.  The ``toctree`` directive is the central element.
 
    **Additional options**
 
-   You can use ``caption`` option to provide toctree caption::
+   You can use ``caption`` option to provide toctree caption and you can use
+   ``name`` option to provide implicit target name that can be referenced by
+   using :rst:role:`ref`::
 
       .. toctree::
          :caption: Table of Contents
+         :name: mastertoc
 
          foo
 
@@ -176,7 +179,7 @@ tables of contents.  The ``toctree`` directive is the central element.
       Added "includehidden" option.
 
    .. versionchanged:: 1.3
-      Added "caption" option.
+      Added "caption" and "name" option.
 
 Special names
 -------------

sphinx/directives/code.py

@@ -93,6 +93,7 @@ class CodeBlock(Directive):
         'lineno-start': int,
         'emphasize-lines': directives.unchanged_required,
         'caption': directives.unchanged_required,
+        'name': directives.unchanged,
     }
 
     def run(self):
@@ -127,8 +128,13 @@ class CodeBlock(Directive):
 
         caption = self.options.get('caption')
         if caption:
+            self.options.setdefault('name', nodes.fully_normalize_name(caption))
             literal = container_wrapper(self, literal, caption)
 
+        # literal will be note_implicit_target that is linked from caption and numref.
+        # when options['name'] is provided, it should be primary ID.
+        self.add_name(literal)
+
         return [literal]
 
 
@@ -159,6 +165,7 @@ class LiteralInclude(Directive):
         'append': directives.unchanged_required,
         'emphasize-lines': directives.unchanged_required,
         'caption': directives.unchanged,
+        'name': directives.unchanged,
         'diff': directives.unchanged_required,
     }
 
@@ -332,10 +339,14 @@ class LiteralInclude(Directive):
 
         caption = self.options.get('caption')
         if caption is not None:
-            if caption:
+            if not caption:
-                retnode = container_wrapper(self, retnode, caption)
+                caption = self.arguments[0]
-            else:
+            self.options.setdefault('name', nodes.fully_normalize_name(caption))
-                retnode = container_wrapper(self, retnode, self.arguments[0])
+            retnode = container_wrapper(self, retnode, caption)
+
+        # retnode will be note_implicit_target that is linked from caption and numref.
+        # when options['name'] is provided, it should be primary ID.
+        self.add_name(retnode)
 
         return [retnode]
 

sphinx/directives/other.py

@@ -40,6 +40,7 @@ class TocTree(Directive):
     final_argument_whitespace = False
     option_spec = {
         'maxdepth': int,
+        'name': directives.unchanged,
         'caption': str,
         'glob': directives.flag,
         'hidden': directives.flag,
@@ -54,7 +55,7 @@ class TocTree(Directive):
         glob = 'glob' in self.options
         caption = self.options.get('caption')
         if caption:
-            self.options['name'] = nodes.fully_normalize_name(caption)
+            self.options.setdefault('name', nodes.fully_normalize_name(caption))
 
         ret = []
         # (title, ref) pairs, where ref may be a document, or an external link,

tests/test_directive_code.py

@@ -55,7 +55,7 @@ def test_code_block_caption_html(app, status, warning):
     html = (app.outdir / 'caption.html').text(encoding='utf-8')
     caption = (u'<div class="code-block-caption">'
                u'<span class="caption-text">caption <em>test</em> rb'
-               u'</span><a class="headerlink" href="#id1" '
+               u'</span><a class="headerlink" href="#caption-test-rb" '
                u'title="Permalink to this code">\xb6</a></div>')
     assert caption in html
 
@@ -178,7 +178,7 @@ def test_literalinclude_caption_html(app, status, warning):
     html = (app.outdir / 'caption.html').text(encoding='utf-8')
     caption = (u'<div class="code-block-caption">'
                u'<span class="caption-text">caption <strong>test</strong> py'
-               u'</span><a class="headerlink" href="#id2" '
+               u'</span><a class="headerlink" href="#caption-test-py" '
                u'title="Permalink to this code">\xb6</a></div>')
     assert caption in html