From 1dc64023562c697882be81eafd462bd7de0f1442 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 6 May 2018 12:49:24 +0200 Subject: [PATCH] m.dox: make it possible to link to arbitrary anchors. Yes, this would clash with anchors inserted by Doxygen itself, but that use case doesn't make any sense anyway. --- doc/plugins/links.rst | 8 +++++++- pelican-plugins/m/dox.py | 21 ++++++++++++++++++--- pelican-plugins/m/test/dox/page.html | 3 +++ pelican-plugins/m/test/dox/page.rst | 3 +++ 4 files changed, 31 insertions(+), 4 deletions(-) diff --git a/doc/plugins/links.rst b/doc/plugins/links.rst index f39d1285..96fba8a1 100644 --- a/doc/plugins/links.rst +++ b/doc/plugins/links.rst @@ -168,7 +168,11 @@ where page/section title is extracted from the tagfile. It's possible to specify custom link title using the :rst:`:dox:`link title `` syntax. If a symbol can't be found, a warning is printed to output and link target is rendered in monospace font (or, if custom link title is specified, -just the title is rendered, as normal text). +just the title is rendered, as normal text). You can append ``#anchor`` to +``link-target`` to link to anchors that are not present in the tag file (such +as ``#details`` for the detailed docs or ``#pub-methods`` for jumping straight +to a list of public member functions), the same works for query parameters +starting with ``?``. .. code-figure:: @@ -179,12 +183,14 @@ just the title is rendered, as normal text). - Page link: :dox:`building-corrade` - :dox:`Custom link title ` - :dox:`Link to documentation index page ` + - :dox:`Link to an anchor ` - Function link: :dox:`Utility::Directory::mkpath()` - Class link: :dox:`Interconnect::Emitter` - Page link: :dox:`building-corrade` - :dox:`Custom link title ` - :dox:`Link to documentation index page ` + - :dox:`Link to an anchor ` `Abbreviations`_ ================ diff --git a/pelican-plugins/m/dox.py b/pelican-plugins/m/dox.py index a5b6f4e2..ccf1f013 100644 --- a/pelican-plugins/m/dox.py +++ b/pelican-plugins/m/dox.py @@ -29,6 +29,7 @@ from docutils.parsers import rst from pelican import signals import xml.etree.ElementTree as ET import os +import re import logging @@ -38,6 +39,20 @@ symbol_mapping = {} symbol_prefixes = [''] tagfile_basenames = [] +# Modified from __init__ to add support for queries and hashes +link_regexp = re.compile(r'(?P.*) <(?P<link>[^?#]+)(?P<hash>[?#].+)?>') + +def parse_link(text): + link = utils.unescape(text) + m = link_regexp.match(link) + if m: + title, link, hash = m.group('title', 'link', 'hash') + if not hash: hash = '' # it's None otherwise + else: + title, hash = '', '' + + return title, link, hash + def init(pelicanobj): global symbol_mapping, symbol_prefixes, tagfile_basenames @@ -100,7 +115,7 @@ def init(pelicanobj): symbol_mapping[section.text] = (section.attrib.get('title', ''), link + '#' + section.text) def dox(name, rawtext, text, lineno, inliner: Inliner, options={}, content=[]): - title, target = parse_link(text) + title, target, hash = parse_link(text) # Try linking to the whole docs first for basename, url in tagfile_basenames: @@ -110,7 +125,7 @@ def dox(name, rawtext, text, lineno, inliner: Inliner, options={}, content=[]): logger.warning("Link to main page `{}` requires a title".format(target)) title = target - node = nodes.reference(rawtext, title, refuri=url, **options) + node = nodes.reference(rawtext, title, refuri=url + hash, **options) return [node], [] for prefix in symbol_prefixes: @@ -125,7 +140,7 @@ def dox(name, rawtext, text, lineno, inliner: Inliner, options={}, content=[]): logger.warning("Doxygen anchor `{}` has no title, using its ID as link title".format(target)) use_title = target - node = nodes.reference(rawtext, use_title, refuri=url, **options) + node = nodes.reference(rawtext, use_title, refuri=url + hash, **options) return [node], [] # TODO: print file and line diff --git a/pelican-plugins/m/test/dox/page.html b/pelican-plugins/m/test/dox/page.html index 87415d1c..aad6bd63 100644 --- a/pelican-plugins/m/test/dox/page.html +++ b/pelican-plugins/m/test/dox/page.html @@ -31,6 +31,9 @@ <li><a href="http://doc.magnum.graphics/corrade/corrade-cmake.html">Page link with custom title</a></li> <li><a href="http://doc.magnum.graphics/corrade/">Link to index page</a></li> <li><a href="http://doc.magnum.graphics/corrade/classCorrade_1_1TestSuite_1_1Tester.html#TestSuite-Tester-command-line">Link to class documentation section</a></li> +<li><a href="http://doc.magnum.graphics/corrade/#search">Link to index page with hash after</a></li> +<li><a href="http://doc.magnum.graphics/corrade/corrade-cmake.html#search">Link to page with hash after</a></li> +<li><a href="http://doc.magnum.graphics/corrade/namespaceCorrade_1_1Utility_1_1Directory.html?q=hello#search">Link to class with query and hash after</a></li> </ul> <p>These should produce warnings:</p> <ul> diff --git a/pelican-plugins/m/test/dox/page.rst b/pelican-plugins/m/test/dox/page.rst index 6f3cfe1d..f401ccf9 100644 --- a/pelican-plugins/m/test/dox/page.rst +++ b/pelican-plugins/m/test/dox/page.rst @@ -8,6 +8,9 @@ m.dox - :dox:`Page link with custom title <corrade-cmake>` - :dox:`Link to index page <corrade>` - :dox:`Link to class documentation section <TestSuite-Tester-command-line>` +- :dox:`Link to index page with hash after <corrade#search>` +- :dox:`Link to page with hash after <corrade-cmake#search>` +- :dox:`Link to class with query and hash after <Utility::Directory?q=hello#search>` These should produce warnings: -- 2.30.2