From 3507ebc38ea0ebd707ade2ef3bdb89cde33c6a88 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Mon, 1 Jan 2018 21:09:03 +0100
Subject: [PATCH] m.dox: ability to link to documentation index pages.

---
 pelican-plugins/m/dox.py             | 16 +++++++++++++++-
 pelican-plugins/m/test/dox/page.html |  3 +++
 pelican-plugins/m/test/dox/page.rst  |  3 +++
 3 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/pelican-plugins/m/dox.py b/pelican-plugins/m/dox.py
index 083ddb02..f3c35d9e 100644
--- a/pelican-plugins/m/dox.py
+++ b/pelican-plugins/m/dox.py
@@ -28,6 +28,7 @@ from docutils import nodes, utils
 from docutils.parsers import rst
 from pelican import signals
 import xml.etree.ElementTree as ET
+import os
 
 import logging
 
@@ -35,15 +36,17 @@ logger = logging.getLogger(__name__)
 
 symbol_mapping = {}
 symbol_prefixes = ['']
+tagfile_basenames = []
 
 def init(pelicanobj):
-    global symbol_mapping, symbol_prefixes
+    global symbol_mapping, symbol_prefixes, tagfile_basenames
 
     tagfiles = pelicanobj.settings.get('M_DOX_TAGFILES', [])
 
     # Pre-round to populate subclasses
 
     for tagfile, path, prefixes in tagfiles:
+        tagfile_basenames += [(os.path.splitext(os.path.basename(tagfile))[0], path)]
         symbol_prefixes += prefixes
 
         tree = ET.parse(tagfile)
@@ -98,6 +101,17 @@ def init(pelicanobj):
 def dox(name, rawtext, text, lineno, inliner: Inliner, options={}, content=[]):
     title, target = parse_link(text)
 
+    # Try linking to the whole docs first
+    for basename, url in tagfile_basenames:
+        if basename == target:
+            if not title:
+                # TODO: extract title from index page in the tagfile
+                logger.warning("Link to main page `{}` requires a title".format(target))
+                title = target
+
+            node = nodes.reference(rawtext, title, refuri=url, **options)
+            return [node], []
+
     for prefix in symbol_prefixes:
         if prefix + target in symbol_mapping:
             link_title, url = symbol_mapping[prefix + target]
diff --git a/pelican-plugins/m/test/dox/page.html b/pelican-plugins/m/test/dox/page.html
index a30bf77a..fc0d953a 100644
--- a/pelican-plugins/m/test/dox/page.html
+++ b/pelican-plugins/m/test/dox/page.html
@@ -29,6 +29,7 @@
 <li>Page link: <a href="http://doc.magnum.graphics/corrade/building-corrade.html">Downloading and building</a></li>
 <li><a href="http://doc.magnum.graphics/corrade/testsuite.html">Custom link title</a></li>
 <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>
 </ul>
 <p>These should produce warnings:</p>
 <ul>
@@ -36,6 +37,8 @@
 <li><span>Link to nonexistent name with custom title will be just text</span></li>
 <li>Link to a section that doesn't have a title will keep the ID (this <em>may</em>
 break on tagfile update, watch out): <a href="http://doc.magnum.graphics/corrade/corrade-cmake.html#corrade-cmake-add-test">corrade-cmake-add-test</a></li>
+<li>Link to index page without title will have the tag file basename:
+<a href="http://doc.magnum.graphics/corrade/">corrade</a></li>
 </ul>
 <!-- /content -->
       </div>
diff --git a/pelican-plugins/m/test/dox/page.rst b/pelican-plugins/m/test/dox/page.rst
index 74b32710..47102b94 100644
--- a/pelican-plugins/m/test/dox/page.rst
+++ b/pelican-plugins/m/test/dox/page.rst
@@ -6,6 +6,7 @@ m.dox
 -   Page link: :dox:`building-corrade`
 -   :dox:`Custom link title <testsuite>`
 -   :dox:`Page link with custom title <corrade-cmake>`
+-   :dox:`Link to index page <corrade>`
 
 These should produce warnings:
 
@@ -13,3 +14,5 @@ These should produce warnings:
 -   :dox:`Link to nonexistent name with custom title will be just text <nonExistent()>`
 -   Link to a section that doesn't have a title will keep the ID (this *may*
     break on tagfile update, watch out): :dox:`corrade-cmake-add-test`
+-   Link to index page without title will have the tag file basename:
+    :dox:`corrade`
-- 
2.30.2