From 69644d0f47fd02043c50e53cc9bda15bde8bb3d8 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 16 Jan 2018 22:29:23 +0100 Subject: [PATCH] doxygen: make it possible to override top navbar links. --- doc/doxygen.rst | 63 ++++++++++++-- doxygen/dox2html5.py | 38 +++++++- doxygen/templates/base-class-reference.html | 1 - doxygen/templates/base.html | 41 +++++++-- doxygen/templates/dir.html | 1 - doxygen/templates/file.html | 1 - doxygen/templates/namespace.html | 1 - doxygen/templates/page.html | 1 - doxygen/test/compound_detailed/Doxyfile | 2 + doxygen/test/compound_detailed/File_8h.html | 14 --- .../test/compound_detailed/namespaceEno.html | 14 --- .../test/compound_detailed/namespaceFoo.html | 14 --- .../compound_detailed/namespaceNamee.html | 14 --- .../test/compound_detailed/namespaceType.html | 14 --- .../test/compound_detailed/namespaceVar.html | 14 --- .../compound_detailed/namespaceWarning.html | 14 --- .../compound_detailed/structTemplate.html | 14 --- .../structTemplateWarning.html | 14 --- .../structTemplate_3_01void_01_4.html | 14 --- doxygen/test/compound_listing/Class_8h.html | 2 +- doxygen/test/compound_listing/Doxyfile | 1 + doxygen/test/compound_listing/File_8h.html | 2 +- ...lassRoot_1_1Directory_1_1Sub_1_1Class.html | 2 +- .../dir_4b0d5f8864bf89936129251a2d32609b.html | 2 +- .../dir_bbe5918fe090eee9db2d9952314b6754.html | 2 +- .../compound_listing/namespaceAnother.html | 2 +- .../namespaceRoot_1_1Directory.html | 2 +- .../test/compound_listing/page-no-toc.html | 2 +- doxygen/test/compound_listing/pages.html | 60 +++++++++++++ doxygen/test/contents_blocks/Doxyfile | 2 + doxygen/test/contents_blocks/File_8h.html | 14 --- doxygen/test/contents_blocks/index.html | 14 --- doxygen/test/contents_blocks/old.html | 14 --- doxygen/test/contents_blocks/todo.html | 14 --- doxygen/test/contents_code/Doxyfile | 2 + doxygen/test/contents_code/index.html | 14 --- doxygen/test/contents_code/warnings.html | 14 --- doxygen/test/contents_code_language/Doxyfile | 2 + doxygen/test/contents_code_language/ansi.html | 14 --- .../test/contents_code_language/index.html | 14 --- .../test/contents_code_language/warnings.html | 14 --- doxygen/test/contents_custom/Doxyfile | 2 + doxygen/test/contents_custom/index.html | 14 --- doxygen/test/contents_custom/math.html | 14 --- doxygen/test/contents_custom/subpage1.html | 14 --- doxygen/test/contents_custom/subpage2.html | 14 --- doxygen/test/contents_image/Doxyfile | 2 + doxygen/test/contents_image/index.html | 14 --- doxygen/test/contents_image/warnings.html | 14 --- doxygen/test/contents_math/Doxyfile | 2 + doxygen/test/contents_math/index.html | 14 --- doxygen/test/contents_tagfile/Doxyfile | 2 + doxygen/test/contents_tagfile/index.html | 14 --- doxygen/test/contents_typography/Doxyfile | 2 + doxygen/test/contents_typography/index.html | 14 --- .../test/contents_typography/warnings.html | 14 --- doxygen/test/cpp_enum_class/Doxyfile | 2 + doxygen/test/cpp_enum_class/File_8h.html | 14 --- doxygen/test/cpp_template_alias/Doxyfile | 2 + doxygen/test/cpp_template_alias/File_8h.html | 14 --- .../cpp_template_alias/structTemplate.html | 14 --- doxygen/test/layout/Doxyfile | 3 + doxygen/test/layout/index.xml | 3 + doxygen/test/layout/pages.html | 87 +++++++++++++++++++ doxygen/test/layout_minimal/index.html | 2 +- .../test/layout_navbar_single_column/Doxyfile | 9 ++ .../index.html | 23 ++--- .../indexpage.xml | 4 +- doxygen/test/page_brief/Doxyfile | 2 + doxygen/test/page_brief/page-a.html | 14 --- doxygen/test/page_brief/page-b.html | 14 --- doxygen/test/page_brief/pages.html | 14 --- doxygen/test/page_in_navbar/Doxyfile | 12 +++ doxygen/test/page_in_navbar/input.dox | 9 ++ doxygen/test/page_in_navbar/page-b.html | 57 ++++++++++++ .../test/page_in_navbar/page-in-navbar.html | 57 ++++++++++++ doxygen/test/page_order/Doxyfile | 2 + doxygen/test/page_order/pages.html | 14 --- doxygen/test/page_toc/Doxyfile | 2 + doxygen/test/page_toc/page-toc.html | 14 --- doxygen/test/test_compound.py | 3 +- doxygen/test/test_doxyfile.py | 2 + doxygen/test/test_layout.py | 12 ++- doxygen/test/test_page.py | 9 ++ 84 files changed, 495 insertions(+), 567 deletions(-) create mode 100644 doxygen/test/compound_listing/pages.html create mode 100644 doxygen/test/layout/index.xml create mode 100644 doxygen/test/layout/pages.html create mode 100644 doxygen/test/layout_navbar_single_column/Doxyfile rename doxygen/test/{layout => layout_navbar_single_column}/index.html (67%) rename doxygen/test/{layout => layout_navbar_single_column}/indexpage.xml (78%) create mode 100644 doxygen/test/page_in_navbar/Doxyfile create mode 100644 doxygen/test/page_in_navbar/input.dox create mode 100644 doxygen/test/page_in_navbar/page-b.html create mode 100644 doxygen/test/page_in_navbar/page-in-navbar.html diff --git a/doc/doxygen.rst b/doc/doxygen.rst index 5aaf3261..d7e35288 100644 --- a/doc/doxygen.rst +++ b/doc/doxygen.rst @@ -240,7 +240,11 @@ Variable Description :ini:`M_THEME_COLOR` Color for :html:``, corresponding to the CSS style. If empty, no :html:`` tag is rendered. See - below for more information. + `Theme selection`_ for more information. +:ini:`M_LINKS_NAVBAR1` Left navbar column links. See + `Navbar links`_ for more information. +:ini:`M_LINKS_NAVBAR2` Right navbar column links. See + `Navbar links`_ for more information. :ini:`M_PAGE_HEADER` HTML code to put at the top of every page. Useful for example to link to different versions of the same documentation. The @@ -267,6 +271,9 @@ Variable Description Note that namespace, directory and page lists are always fully expanded as these are not expected to be excessively large. +`Theme selection`_ +------------------ + By default, the `dark m.css theme <{filename}/css/themes.rst#dark>`_ together with Doxygen-theme-specific additions is used, which corresponds to the following configuration: @@ -306,6 +313,42 @@ place of ``m-light+doxygen.compiled.css``: See the `CSS files`_ section below for more information about customizing the CSS files. +`Navbar links`_ +--------------- + +The :ini:`M_LINKS_NAVBAR1` and :ini:`M_LINKS_NAVBAR2` options define which +links are shown on the top navbar, split into left and right column on small +screen sizes. These options take a whitespace-separated list of compound IDs +and additionally the special ``pages``, ``namespaces``, ``annotated``, +``files`` IDs. By default the variables are defined like following: + +.. code:: ini + + M_LINKS_NAVBAR1 = pages namespaces + M_LINKS_NAVBAR2 = annotated files + +Titles for the links are taken implicitly. Empty :ini:`M_LINKS_NAVBAR2` will +cause the navigation appear in a single column, setting both empty will cause +the navbar links to not be rendered at all. + +A menu item is higlighted if a compound with the same ID is the current page +(and similarly for the special ``pages``, ... IDs). + +It's possible to specify sub-menu items by enclosing more than one ID in +quotes. The top-level items then have to be specified each on a single line. +Example (note the mangled names, corresponding to filenames of given compounds +generated by Doxygen): + +.. code:: ini + + M_LINKS_NAVBAR1 = \ + "namespaces namespaceFoo namespaceBar namespaceUtils" \ + "files dir_d3b07384d113edec49eaa6238ad5ff00 dir_cbd8f7984c654c25512e3d9241ae569f" + +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. + `Command-line options`_ ======================= @@ -708,7 +751,17 @@ Filename Use ======================= ======================================================= Each template is passed a subset of the ``Doxyfile`` configuration values from -the above table and in addition the following variables: +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)`. + + and in addition the following variables: .. class:: m-table m-fullwidth @@ -719,9 +772,9 @@ Variable Description :py:`DOXYGEN_VERSION` Version of Doxygen that generated given XML file =========================== =================================================== -In addition to builtin Jinja2 filters, the the ``basename_or_url`` filter -returns either a basename of file path, if the path is relative; or a full URL, -if the argument is an absolute URL. It's useful in cases like this: +In addition to builtin Jinja2 filters, the ``basename_or_url`` filter returns +either a basename of file path, if the path is relative; or a full URL, if the +argument is an absolute URL. It's useful in cases like this: .. code:: html+jinja diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index ba9fec2c..08728a9b 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -1204,6 +1204,38 @@ def build_tree(state: State): # Other compounds are not in any index pages or breadcrumb, so leaf # name not needed + # Assign names and URLs to menu items + predefined = { + 'pages': ("Pages", 'pages.html'), + 'namespaces': ("Namespaces", 'namespaces.html'), + 'annotated': ("Classes", 'annotated.html'), + 'files': ("Files", 'files.html') + } + + def find(id): + # If predefined, return those + if id in predefined: + return predefined[id] + + # Otherwise search in symbols + found = state.compounds[id] + return found.name, found.url + + i: str + for var in 'M_LINKS_NAVBAR1', 'M_LINKS_NAVBAR2': + navbar_links = [] + for i in state.doxyfile[var]: + links = i.split() + assert len(links) + 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)] + + state.doxyfile[var] = navbar_links + def parse_xml(state: State, xml: str): # Reset counter for unique math formulas m.math.counter = 0 @@ -1774,6 +1806,8 @@ def parse_doxyfile(state: State, doxyfile, config = None): 'M_FILE_TREE_EXPAND_LEVELS': ['1'], 'M_EXPAND_INNER_TYPES': ['NO'], 'M_THEME_COLOR': ['#22272e'], + 'M_LINKS_NAVBAR1': ['pages', 'namespaces'], + 'M_LINKS_NAVBAR2': ['annotated', 'files'], 'M_PAGE_FINE_PRINT': ['[default]'] } @@ -1865,7 +1899,9 @@ def parse_doxyfile(state: State, doxyfile, config = None): # List values that we want. Drop empty lines. for i in ['TAGFILES', 'HTML_EXTRA_STYLESHEET', - 'HTML_EXTRA_FILES']: + 'HTML_EXTRA_FILES', + 'M_LINKS_NAVBAR1', + 'M_LINKS_NAVBAR2']: if i in config: state.doxyfile[i] = [line for line in config[i] if line] diff --git a/doxygen/templates/base-class-reference.html b/doxygen/templates/base-class-reference.html index 7931e538..48d59247 100644 --- a/doxygen/templates/base-class-reference.html +++ b/doxygen/templates/base-class-reference.html @@ -1,4 +1,3 @@ -{% set navbar_current = 'annotated' %} {% extends 'base.html' %} {% macro entry_class(class) %}{% include 'entry-class.html' %}{% endmacro %} diff --git a/doxygen/templates/base.html b/doxygen/templates/base.html index 6715bccd..deb57d09 100644 --- a/doxygen/templates/base.html +++ b/doxygen/templates/base.html @@ -18,20 +18,49 @@
{{ PROJECT_NAME }}{% if PROJECT_BRIEF %} {{ PROJECT_BRIEF }}{% endif %} + {% if M_LINKS_NAVBAR1 or M_LINKS_NAVBAR2 %} + {% endif %}
diff --git a/doxygen/templates/dir.html b/doxygen/templates/dir.html index 1d54c5e5..666f07d0 100644 --- a/doxygen/templates/dir.html +++ b/doxygen/templates/dir.html @@ -1,4 +1,3 @@ -{% set navbar_current = 'files' %} {% extends 'base-reference.html' %} {% block title %}{% for name, _ in compound.breadcrumb %}{{ name }}/{% endfor %} directory | {{ super() }}{% endblock %} diff --git a/doxygen/templates/file.html b/doxygen/templates/file.html index 8ded452a..126ccaa5 100644 --- a/doxygen/templates/file.html +++ b/doxygen/templates/file.html @@ -1,4 +1,3 @@ -{% set navbar_current = 'files' %} {% extends 'base-reference.html' %} {% block title %}{% set j = joiner('/') %}{% for name, _ in compound.breadcrumb %}{{ j() }}{{ name }}{% endfor %} file | {{ super() }}{% endblock %} diff --git a/doxygen/templates/namespace.html b/doxygen/templates/namespace.html index e829c15e..a90756af 100644 --- a/doxygen/templates/namespace.html +++ b/doxygen/templates/namespace.html @@ -1,4 +1,3 @@ -{% set navbar_current = 'namespaces' %} {% extends 'base-reference.html' %} {% block title %}{% set j = joiner('::') %}{% for name, _ in compound.breadcrumb %}{{ j() }}{{ name }}{% endfor %} namespace | {{ super() }}{% endblock %} diff --git a/doxygen/templates/page.html b/doxygen/templates/page.html index a4c7ebc0..fb5f8926 100644 --- a/doxygen/templates/page.html +++ b/doxygen/templates/page.html @@ -1,4 +1,3 @@ -{% set navbar_current = 'pages' %} {% extends 'base.html' %} {% block title %}{% if 1 in compound.breadcrumb or compound.breadcrumb[-1][0] != PROJECT_NAME %}{% set j = joiner(' » ') %}{% for name, _ in compound.breadcrumb %}{{ j() }}{{ name }}{% endfor %} | {{ super() }}{% else %}{{ super() }}{% endif %}{% endblock %} diff --git a/doxygen/test/compound_detailed/Doxyfile b/doxygen/test/compound_detailed/Doxyfile index c25c5697..262c1550 100644 --- a/doxygen/test/compound_detailed/Doxyfile +++ b/doxygen/test/compound_detailed/Doxyfile @@ -7,3 +7,5 @@ GENERATE_XML = YES M_PAGE_FINE_PRINT = M_THEME_COLOR = +M_LINKS_NAVBAR1 = +M_LINKS_NAVBAR2 = diff --git a/doxygen/test/compound_detailed/File_8h.html b/doxygen/test/compound_detailed/File_8h.html index 7cb7671b..4eff1f6f 100644 --- a/doxygen/test/compound_detailed/File_8h.html +++ b/doxygen/test/compound_detailed/File_8h.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/namespaceEno.html b/doxygen/test/compound_detailed/namespaceEno.html index 9c2f9caa..d79a35ad 100644 --- a/doxygen/test/compound_detailed/namespaceEno.html +++ b/doxygen/test/compound_detailed/namespaceEno.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/namespaceFoo.html b/doxygen/test/compound_detailed/namespaceFoo.html index 191d5795..29f2ba6e 100644 --- a/doxygen/test/compound_detailed/namespaceFoo.html +++ b/doxygen/test/compound_detailed/namespaceFoo.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/namespaceNamee.html b/doxygen/test/compound_detailed/namespaceNamee.html index ede9b314..88397c94 100644 --- a/doxygen/test/compound_detailed/namespaceNamee.html +++ b/doxygen/test/compound_detailed/namespaceNamee.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/namespaceType.html b/doxygen/test/compound_detailed/namespaceType.html index 0264db6f..81fbd143 100644 --- a/doxygen/test/compound_detailed/namespaceType.html +++ b/doxygen/test/compound_detailed/namespaceType.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/namespaceVar.html b/doxygen/test/compound_detailed/namespaceVar.html index c5e7acf1..7e831743 100644 --- a/doxygen/test/compound_detailed/namespaceVar.html +++ b/doxygen/test/compound_detailed/namespaceVar.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/namespaceWarning.html b/doxygen/test/compound_detailed/namespaceWarning.html index 02778f03..ab9d2ecd 100644 --- a/doxygen/test/compound_detailed/namespaceWarning.html +++ b/doxygen/test/compound_detailed/namespaceWarning.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/structTemplate.html b/doxygen/test/compound_detailed/structTemplate.html index d3824c22..a043b749 100644 --- a/doxygen/test/compound_detailed/structTemplate.html +++ b/doxygen/test/compound_detailed/structTemplate.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/structTemplateWarning.html b/doxygen/test/compound_detailed/structTemplateWarning.html index 2d838cb6..feb96dbd 100644 --- a/doxygen/test/compound_detailed/structTemplateWarning.html +++ b/doxygen/test/compound_detailed/structTemplateWarning.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_detailed/structTemplate_3_01void_01_4.html b/doxygen/test/compound_detailed/structTemplate_3_01void_01_4.html index 8954624c..0ca49744 100644 --- a/doxygen/test/compound_detailed/structTemplate_3_01void_01_4.html +++ b/doxygen/test/compound_detailed/structTemplate_3_01void_01_4.html @@ -12,20 +12,6 @@
My Project - - -
diff --git a/doxygen/test/compound_listing/Class_8h.html b/doxygen/test/compound_listing/Class_8h.html index 86bd8126..a3922347 100644 --- a/doxygen/test/compound_listing/Class_8h.html +++ b/doxygen/test/compound_listing/Class_8h.html @@ -22,7 +22,7 @@
  1. Classes
    2. -
  2. Files
    3. +
  3. Files
diff --git a/doxygen/test/compound_listing/Doxyfile b/doxygen/test/compound_listing/Doxyfile index 82f23188..d1821c27 100644 --- a/doxygen/test/compound_listing/Doxyfile +++ b/doxygen/test/compound_listing/Doxyfile @@ -12,3 +12,4 @@ M_CLASS_TREE_EXPAND_LEVELS = 5 M_EXPAND_INNER_TYPES = YES M_PAGE_FINE_PRINT = M_THEME_COLOR = +# Keeping navbar enabled so we can test for highlighted items diff --git a/doxygen/test/compound_listing/File_8h.html b/doxygen/test/compound_listing/File_8h.html index 5c5856e5..a304ca19 100644 --- a/doxygen/test/compound_listing/File_8h.html +++ b/doxygen/test/compound_listing/File_8h.html @@ -22,7 +22,7 @@
  1. Classes
    2. -
  2. Files
    3. +
  3. Files
diff --git a/doxygen/test/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html b/doxygen/test/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html index 9443cc2d..1c3a70e5 100644 --- a/doxygen/test/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html +++ b/doxygen/test/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html @@ -21,7 +21,7 @@
  • Namespaces
      • -
    1. Classes
      2. +
    2. Classes
    3. Files
    diff --git a/doxygen/test/compound_listing/dir_4b0d5f8864bf89936129251a2d32609b.html b/doxygen/test/compound_listing/dir_4b0d5f8864bf89936129251a2d32609b.html index 2a50f752..a3cde8ff 100644 --- a/doxygen/test/compound_listing/dir_4b0d5f8864bf89936129251a2d32609b.html +++ b/doxygen/test/compound_listing/dir_4b0d5f8864bf89936129251a2d32609b.html @@ -22,7 +22,7 @@
    1. Classes
      2. -
    2. Files
      3. +
    3. Files
    diff --git a/doxygen/test/compound_listing/dir_bbe5918fe090eee9db2d9952314b6754.html b/doxygen/test/compound_listing/dir_bbe5918fe090eee9db2d9952314b6754.html index a63821a9..aca3ac2b 100644 --- a/doxygen/test/compound_listing/dir_bbe5918fe090eee9db2d9952314b6754.html +++ b/doxygen/test/compound_listing/dir_bbe5918fe090eee9db2d9952314b6754.html @@ -22,7 +22,7 @@
    1. Classes
      2. -
    2. Files
      3. +
    3. Files
    diff --git a/doxygen/test/compound_listing/namespaceAnother.html b/doxygen/test/compound_listing/namespaceAnother.html index a3e9099a..2093dfba 100644 --- a/doxygen/test/compound_listing/namespaceAnother.html +++ b/doxygen/test/compound_listing/namespaceAnother.html @@ -18,7 +18,7 @@
    1. Pages
      2. -
    2. Namespaces
      3. +
    3. Namespaces
    1. Classes
      2. diff --git a/doxygen/test/compound_listing/namespaceRoot_1_1Directory.html b/doxygen/test/compound_listing/namespaceRoot_1_1Directory.html index e7460f5e..f11c2c5f 100644 --- a/doxygen/test/compound_listing/namespaceRoot_1_1Directory.html +++ b/doxygen/test/compound_listing/namespaceRoot_1_1Directory.html @@ -18,7 +18,7 @@
      1. Pages
        2. -
      2. Namespaces
        3. +
      3. Namespaces
      1. Classes
        2. diff --git a/doxygen/test/compound_listing/page-no-toc.html b/doxygen/test/compound_listing/page-no-toc.html index becccef0..72ca7678 100644 --- a/doxygen/test/compound_listing/page-no-toc.html +++ b/doxygen/test/compound_listing/page-no-toc.html @@ -17,7 +17,7 @@