From 7717b022055939f47ff160c5f69de4565cc8584a Mon Sep 17 00:00:00 2001 From: Walter Doerwald Date: Fri, 5 Jul 2019 18:34:20 +0200 Subject: [PATCH 1/6] Allow custom link texts for permalinks and links to source code. --- doc/usage/configuration.rst | 6 ++++++ doc/usage/extensions/viewcode.rst | 6 ++++++ sphinx/addnodes.py | 4 ++++ sphinx/builders/html.py | 1 + sphinx/ext/viewcode.py | 3 ++- sphinx/writers/html.py | 5 +++++ sphinx/writers/html5.py | 12 ++++++++++++ 7 files changed, 36 insertions(+), 1 deletion(-) diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 6619c50151f..1f23d2aac05 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1034,6 +1034,12 @@ that use Sphinx's HTMLWriter class. This can now be a string to select the actual text of the link. Previously, only boolean values were accepted. +.. confval:: html_add_permalinks_html + + The text for the permalink can also be specified as an HTML string. If both + ``html_add_permalinks`` and ``html_add_permalinks_html`` are specified, + ``html_add_permalinks_html`` wins. + .. confval:: html_sidebars Custom sidebar templates, must be a dictionary that maps document names to diff --git a/doc/usage/extensions/viewcode.rst b/doc/usage/extensions/viewcode.rst index d3c3c44fbd5..b1570e66861 100644 --- a/doc/usage/extensions/viewcode.rst +++ b/doc/usage/extensions/viewcode.rst @@ -73,6 +73,12 @@ Configuration `epubcheck `_'s score becomes worse even if the reader supports. +.. confval:: viewcode_source_html + + Can be set to the HTML code for the link to the source code. If this is not + specified it defaults to ``'[source]'`` + (with ``[source]`` getting localized). + .. event:: viewcode-find-source (app, modname) .. versionadded:: 1.8 diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 4180625ca0d..a726c8e77f5 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -307,6 +307,10 @@ class manpage(nodes.Inline, nodes.FixedTextElement): """Node for references to manpages.""" +class viewcode_source(nodes.Part, nodes.Inline, nodes.FixedTextElement): + """Node for the link text for a source link.""" + + def setup(app): # type: (Sphinx) -> Dict[str, Any] app.add_node(toctree) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index fed558c228e..ad22bede2dc 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -1166,6 +1166,7 @@ def setup(app: Sphinx) -> Dict[str, Any]: app.add_config_value('html_additional_pages', {}, 'html') app.add_config_value('html_domain_indices', True, 'html', [list]) app.add_config_value('html_add_permalinks', '¶', 'html') + app.add_config_value('html_add_permalinks_html', None, 'html') app.add_config_value('html_use_index', True, 'html') app.add_config_value('html_split_index', False, 'html') app.add_config_value('html_copy_source', True, 'html') diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index 5de8f7f5eb2..0c3c04c5e27 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -112,7 +112,7 @@ def has_tag(modname, fullname, docname, refname): continue names.add(fullname) pagename = '_modules/' + modname.replace('.', '/') - inline = nodes.inline('', _('[source]'), classes=['viewcode-link']) + inline = addnodes.viewcode_source() onlynode = addnodes.only(expr='html') onlynode += addnodes.pending_xref('', inline, reftype='viewcode', refdomain='std', refexplicit=False, reftarget=pagename, @@ -241,6 +241,7 @@ def setup(app): app.add_config_value('viewcode_import', None, False) app.add_config_value('viewcode_enable_epub', False, False) app.add_config_value('viewcode_follow_imported_members', True, False) + app.add_config_value('viewcode_sourcelink_html', None, False) app.connect('doctree-read', doctree_read) app.connect('env-merge-info', env_merge_info) app.connect('html-collect-pages', collect_pages) diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 9ac76901bc5..8de1cb1fb4a 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -93,6 +93,11 @@ def __init__(self, *args): if not isinstance(self.permalink_text, str): self.permalink_text = self.permalink_text and '¶' or '' self.permalink_text = self.encode(self.permalink_text) + if self.config.html_add_permalinks_html: + self.permalink_text = self.config.html_add_permalinks_html + self.viewcode_source = self.config.viewcode_source_html + if not self.viewcode_source: + self.viewcode_source = '%s' % _('[source]') self.secnumber_suffix = self.config.html_secnumber_suffix self.param_separator = '' self.optional_param_level = 0 diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py index fe57f42bff5..ecad6629873 100644 --- a/sphinx/writers/html5.py +++ b/sphinx/writers/html5.py @@ -63,6 +63,11 @@ def __init__(self, *args): if not isinstance(self.permalink_text, str): self.permalink_text = self.permalink_text and '¶' or '' self.permalink_text = self.encode(self.permalink_text) + if self.config.html_add_permalinks_html: + self.permalink_text = self.config.html_add_permalinks_html + self.viewcode_source = self.config.viewcode_source_html + if not self.viewcode_source: + self.viewcode_source = '%s' % _('[source]') self.secnumber_suffix = self.config.html_secnumber_suffix self.param_separator = '' self.optional_param_level = 0 @@ -218,6 +223,13 @@ def depart_versionmodified(self, node): # type: (nodes.Element) -> None self.body.append('\n') + def visit_viewcode_source(self, node): + self.body.append(self.viewcode_source) + raise nodes.SkipNode + + def depart_viewcode_source(self, node): + pass + # overwritten def visit_reference(self, node): # type: (nodes.Element) -> None From 58c83d1b537f1a46a13e953a2925e91c873ea507 Mon Sep 17 00:00:00 2001 From: Walter Doerwald Date: Mon, 8 Jul 2019 18:12:36 +0200 Subject: [PATCH 2/6] Fix name of config variable. --- sphinx/ext/viewcode.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index 0c3c04c5e27..410965499b0 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -241,7 +241,7 @@ def setup(app): app.add_config_value('viewcode_import', None, False) app.add_config_value('viewcode_enable_epub', False, False) app.add_config_value('viewcode_follow_imported_members', True, False) - app.add_config_value('viewcode_sourcelink_html', None, False) + app.add_config_value('viewcode_source_html', None, False) app.connect('doctree-read', doctree_read) app.connect('env-merge-info', env_merge_info) app.connect('html-collect-pages', collect_pages) From 108d35a201ec883318a21f4b361df6afe0da129b Mon Sep 17 00:00:00 2001 From: Walter Doerwald Date: Mon, 8 Jul 2019 18:27:07 +0200 Subject: [PATCH 3/6] Rebuild html when viecode_source_html changes. --- sphinx/ext/viewcode.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index 410965499b0..37633b48b1f 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -241,7 +241,7 @@ def setup(app): app.add_config_value('viewcode_import', None, False) app.add_config_value('viewcode_enable_epub', False, False) app.add_config_value('viewcode_follow_imported_members', True, False) - app.add_config_value('viewcode_source_html', None, False) + app.add_config_value('viewcode_source_html', None, 'html') app.connect('doctree-read', doctree_read) app.connect('env-merge-info', env_merge_info) app.connect('html-collect-pages', collect_pages) From 2d5db7e604c471f2069c4576eb1919258213c2b7 Mon Sep 17 00:00:00 2001 From: Walter Doerwald Date: Mon, 8 Jul 2019 18:27:33 +0200 Subject: [PATCH 4/6] Handle noon-existant extension option. --- sphinx/writers/html.py | 2 +- sphinx/writers/html5.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 8de1cb1fb4a..1511ce698fb 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -95,7 +95,7 @@ def __init__(self, *args): self.permalink_text = self.encode(self.permalink_text) if self.config.html_add_permalinks_html: self.permalink_text = self.config.html_add_permalinks_html - self.viewcode_source = self.config.viewcode_source_html + self.viewcode_source = getattr(self.config, 'viewcode_source_html', None) if not self.viewcode_source: self.viewcode_source = '%s' % _('[source]') self.secnumber_suffix = self.config.html_secnumber_suffix diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py index ecad6629873..ce307aec9d5 100644 --- a/sphinx/writers/html5.py +++ b/sphinx/writers/html5.py @@ -65,7 +65,7 @@ def __init__(self, *args): self.permalink_text = self.encode(self.permalink_text) if self.config.html_add_permalinks_html: self.permalink_text = self.config.html_add_permalinks_html - self.viewcode_source = self.config.viewcode_source_html + self.viewcode_source = getattr(self.config, 'viewcode_source_html', None) if not self.viewcode_source: self.viewcode_source = '%s' % _('[source]') self.secnumber_suffix = self.config.html_secnumber_suffix From 1719744c41ce654b500360b9ffcefc2416a9b185 Mon Sep 17 00:00:00 2001 From: Walter Doerwald Date: Fri, 10 Jul 2020 18:23:52 +0200 Subject: [PATCH 5/6] Remove support for change the "viewcode" source --- doc/usage/extensions/viewcode.rst | 6 ------ sphinx/addnodes.py | 4 ---- sphinx/ext/viewcode.py | 3 +-- sphinx/writers/html.py | 3 --- sphinx/writers/html5.py | 7 ------- 5 files changed, 1 insertion(+), 22 deletions(-) diff --git a/doc/usage/extensions/viewcode.rst b/doc/usage/extensions/viewcode.rst index b1570e66861..d3c3c44fbd5 100644 --- a/doc/usage/extensions/viewcode.rst +++ b/doc/usage/extensions/viewcode.rst @@ -73,12 +73,6 @@ Configuration `epubcheck `_'s score becomes worse even if the reader supports. -.. confval:: viewcode_source_html - - Can be set to the HTML code for the link to the source code. If this is not - specified it defaults to ``'[source]'`` - (with ``[source]`` getting localized). - .. event:: viewcode-find-source (app, modname) .. versionadded:: 1.8 diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index a726c8e77f5..4180625ca0d 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -307,10 +307,6 @@ class manpage(nodes.Inline, nodes.FixedTextElement): """Node for references to manpages.""" -class viewcode_source(nodes.Part, nodes.Inline, nodes.FixedTextElement): - """Node for the link text for a source link.""" - - def setup(app): # type: (Sphinx) -> Dict[str, Any] app.add_node(toctree) diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index 37633b48b1f..5de8f7f5eb2 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -112,7 +112,7 @@ def has_tag(modname, fullname, docname, refname): continue names.add(fullname) pagename = '_modules/' + modname.replace('.', '/') - inline = addnodes.viewcode_source() + inline = nodes.inline('', _('[source]'), classes=['viewcode-link']) onlynode = addnodes.only(expr='html') onlynode += addnodes.pending_xref('', inline, reftype='viewcode', refdomain='std', refexplicit=False, reftarget=pagename, @@ -241,7 +241,6 @@ def setup(app): app.add_config_value('viewcode_import', None, False) app.add_config_value('viewcode_enable_epub', False, False) app.add_config_value('viewcode_follow_imported_members', True, False) - app.add_config_value('viewcode_source_html', None, 'html') app.connect('doctree-read', doctree_read) app.connect('env-merge-info', env_merge_info) app.connect('html-collect-pages', collect_pages) diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 1511ce698fb..4fb2e0e330d 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -95,9 +95,6 @@ def __init__(self, *args): self.permalink_text = self.encode(self.permalink_text) if self.config.html_add_permalinks_html: self.permalink_text = self.config.html_add_permalinks_html - self.viewcode_source = getattr(self.config, 'viewcode_source_html', None) - if not self.viewcode_source: - self.viewcode_source = '%s' % _('[source]') self.secnumber_suffix = self.config.html_secnumber_suffix self.param_separator = '' self.optional_param_level = 0 diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py index ce307aec9d5..7632ba40f05 100644 --- a/sphinx/writers/html5.py +++ b/sphinx/writers/html5.py @@ -65,9 +65,6 @@ def __init__(self, *args): self.permalink_text = self.encode(self.permalink_text) if self.config.html_add_permalinks_html: self.permalink_text = self.config.html_add_permalinks_html - self.viewcode_source = getattr(self.config, 'viewcode_source_html', None) - if not self.viewcode_source: - self.viewcode_source = '%s' % _('[source]') self.secnumber_suffix = self.config.html_secnumber_suffix self.param_separator = '' self.optional_param_level = 0 @@ -223,10 +220,6 @@ def depart_versionmodified(self, node): # type: (nodes.Element) -> None self.body.append('\n') - def visit_viewcode_source(self, node): - self.body.append(self.viewcode_source) - raise nodes.SkipNode - def depart_viewcode_source(self, node): pass From 1b4d519d29bd9203841cdbfdc147231e9f6750fb Mon Sep 17 00:00:00 2001 From: Walter Doerwald Date: Fri, 10 Jul 2020 18:35:57 +0200 Subject: [PATCH 6/6] Remove depart_viewcode_source() --- sphinx/writers/html5.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/sphinx/writers/html5.py b/sphinx/writers/html5.py index 422b92f7954..c982d52e443 100644 --- a/sphinx/writers/html5.py +++ b/sphinx/writers/html5.py @@ -194,9 +194,6 @@ def visit_versionmodified(self, node: Element) -> None: def depart_versionmodified(self, node: Element) -> None: self.body.append('\n') - def depart_viewcode_source(self, node): - pass - # overwritten def visit_reference(self, node: Element) -> None: atts = {'class': 'reference'}