diff --git a/CHANGES b/CHANGES index d4f5b93bf..d068c948e 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 9a503519d..c76726441 100644 --- a/doc/markup/code.rst +++ b/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 -example:: +A ``caption`` option can be given to show that name before the code block. +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 -additional feature that if you leave the value empty, the shown filename will be -exactly the one given as an argument. +:rst:dir:`literalinclude` also supports the ``caption`` and ``name`` option. +``caption`` has a additional feature that if you leave the value empty, the shown +filename will be exactly the one given as an argument. Dedent diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst index 7c6cbc44c..ff0af7535 100644 --- a/doc/markup/toctree.rst +++ b/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 ------------- diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index ea28ff1ed..1f7a856a7 100644 --- a/sphinx/directives/code.py +++ b/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: - retnode = container_wrapper(self, retnode, caption) - else: - retnode = container_wrapper(self, retnode, self.arguments[0]) + if not caption: + caption = self.arguments[0] + self.options.setdefault('name', nodes.fully_normalize_name(caption)) + 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] diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 1acf9593e..468b504e5 100644 --- a/sphinx/directives/other.py +++ b/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, diff --git a/tests/test_directive_code.py b/tests/test_directive_code.py index d8cb2794c..ba4687cc0 100644 --- a/tests/test_directive_code.py +++ b/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'
' u'caption test rb' - u'\xb6
') 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'
' u'caption test py' - u'\xb6
') assert caption in html