From: Vladimír Vondruš Date: Thu, 11 Oct 2018 10:49:32 +0000 (+0200) Subject: doxygen: support arbitrary HTML for navbar links. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=33fb894caa4fb9602c33c8eebeeeed804ce11775;p=blog.git doxygen: support arbitrary HTML for navbar links. --- diff --git a/doc/doxygen.rst b/doc/doxygen.rst index b2193e42..a1a6381c 100644 --- a/doc/doxygen.rst +++ b/doc/doxygen.rst @@ -468,6 +468,19 @@ This will put links to namespaces Foo, Bar and Utils as a sub-items of a top-level *Namespaces* item and links to two subdirectories as sub-items of the *Files* item. +For custom links in the navbar it's possible to use HTML code directly, both +for a top-level item or in a submenu. The item is taken as everything from the +initial :html:``. In the following snippet, +there are two top-level items, first linking to the page index and having a +submenu linking to an e-mail address and a ``fine-print`` page and the second +linking to a GitHub project page: + +.. code:: ini + + M_LINKS_NAVBAR2 = \ + "pages Contact fine-print" \ + "GitHub" + `Search options`_ ----------------- @@ -1220,11 +1233,13 @@ the `Configuration`_ table. Most values are provided as-is depending on their type, so either strings, booleans, or lists of strings. The exceptions are: - The :py:`M_LINKS_NAVBAR1` and :py:`M_LINKS_NAVBAR2` are processed to tuples - in a form :py:`(title, url, id, sub)` where :py:`title` is link title, - :py:`url` is link URL, :py:`id` is compound ID (to use for highlighting - active menu item) and :py:`sub` is a list optionally containing sub-menu - items. The sub-menu items are in a similarly formed tuple, - :py:`(title, url, id)`. + in a form :py:`(html, title, url, id, sub)` where either :py:`html` is a + full HTML code for the link and :py:`title`, :py:`url` :py:`id` is empty; + or :py:`html` is :py:`None`, :py:`title` and :py:`url` is a link title and + URL and :py:`id` is compound ID (to use for highlighting active menu item). + The last item, :py:`sub` is a list optionally containing sub-menu items. + The sub-menu items are in a similarly formed tuple, + :py:`(html, title, url, id)`. - The :py:`M_FAVICON` is converted to a tuple of :py:`(url, type)` where :py:`url` is the favicon URL and :py:`type` is favicon MIME type to populate the ``type`` attribute of :html:``. diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 7d0abde8..e53bf8fb 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -1889,36 +1889,58 @@ def postprocess_state(state: State): # Other compounds are not in any index pages or breadcrumb, so leaf # name not needed - # Assign names and URLs to menu items + # Assign names and URLs to menu items. The link can be either a predefined + # keyword from the below list, a Doxygen symbol, or a HTML code. The + # template then gets a tuple of (HTML code, title, URL) and either puts + # in the HTML code verbatim (if it's not empty) or creates a link from the + # title and URL. predefined = { - 'pages': ("Pages", 'pages.html'), - 'namespaces': ("Namespaces", 'namespaces.html'), - 'modules': ("Modules", 'modules.html'), - 'annotated': ("Classes", 'annotated.html'), - 'files': ("Files", 'files.html') + 'pages': (None, "Pages", 'pages.html'), + 'namespaces': (None, "Namespaces", 'namespaces.html'), + 'modules': (None, "Modules", 'modules.html'), + 'annotated': (None, "Classes", 'annotated.html'), + 'files': (None, "Files", 'files.html') } + def extract_link(link): + # If this is a HTML code, return it verbatim + if link.startswith(' elements. If it looks like a HTML, take everything until + # the closing , otherwise take everything until the next + # whitespace. + links = [] + while i: + if i.startswith('') + 4 + links += [i[0:end]] + i = i[end:] + else: + firstAndRest = i.split(None, 1) + if len(firstAndRest): + links += [firstAndRest[0]] + if len(firstAndRest) == 1: + break; + i = firstAndRest[1] + sublinks = [] for sublink in links[1:]: - title, url = find(sublink) - sublinks += [(title, url, sublink)] - title, url = find(links[0]) - navbar_links += [(title, url, links[0], sublinks)] + html, title, url = extract_link(sublink) + sublinks += [(html, title, url, sublink)] + html, title, url = extract_link(links[0]) + navbar_links += [(html, title, url, links[0], sublinks)] state.doxyfile[var] = navbar_links diff --git a/doxygen/templates/base.html b/doxygen/templates/base.html index 205cbc33..db26ec0a 100644 --- a/doxygen/templates/base.html +++ b/doxygen/templates/base.html @@ -37,15 +37,19 @@