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.

diff --git a/doc/plugins/links.rst b/doc/plugins/links.rst
index f39d128577745cfa86f4f8a48f72e53baea2e79d..96fba8a186bbd5f07fb5253a1496f49fd2611153 100644 (file)
--- 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 <link-target>``
 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 <testsuite>`
         -   :dox:`Link to documentation index page <corrade>`
+        -   :dox:`Link to an anchor <Interconnect::Emitter#pub-methods>`
 
     -   Function link: :dox:`Utility::Directory::mkpath()`
     -   Class link: :dox:`Interconnect::Emitter`
     -   Page link: :dox:`building-corrade`
     -   :dox:`Custom link title <testsuite>`
     -   :dox:`Link to documentation index page <corrade>`
+    -   :dox:`Link to an anchor <Interconnect::Emitter#pub-methods>`
 
 `Abbreviations`_
 ================

diff --git a/pelican-plugins/m/dox.py b/pelican-plugins/m/dox.py
index a5b6f4e2db3b3504bc293c81117d9c351554587c..ccf1f0138129fa844579f856fb1124797d14230c 100644 (file)
--- 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<title>.*) <(?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 87415d1c2159197b016ef9d5668c3d33ed5aa972..aad6bd634885bca405afbf1dc919bcdf3c05b578 100644 (file)
--- 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 6f3cfe1d6b07d917a6a827b03d53b1c750518ac2..f401ccf99101fd4e24817509d3db2c139814ac96 100644 (file)
--- 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: