From: Vladimír Vondruš Date: Thu, 14 Dec 2017 23:12:33 +0000 (+0100) Subject: doxygen: new @m_footernavigation command. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=91acede72ad7e9abcd4339aab48c5eea05f85aab;p=blog.git doxygen: new @m_footernavigation command. --- diff --git a/doc/doxygen.rst b/doc/doxygen.rst index 0ac78290..66f9fa51 100644 --- a/doc/doxygen.rst +++ b/doc/doxygen.rst @@ -568,8 +568,8 @@ aliases in the original ``Doxyfile``: Doxygen with :gh:`doxygen/doxygen#623` applied, otherwise the codes will be present in the rendered output in their raw form. -`Custom styling`_ ------------------ +`Theme-specific commands`_ +-------------------------- It's possible to insert custom m.css classes into the Doxygen output. Add the following to your ``Doxyfile-mcss``: @@ -581,7 +581,8 @@ following to your ``Doxyfile-mcss``: "m_enddiv=@xmlonly@endxmlonly" \ "m_span{1}=@xmlonly@endxmlonly" \ "m_endspan=@xmlonly@endxmlonly" \ - "m_class{1}=@xmlonly@endxmlonly" + "m_class{1}=@xmlonly@endxmlonly" \ + "m_footernavigation=@xmlonly@endxmlonly" If you need backwards compatibility with stock Doxygen HTML output, just make the aliases empty in your original ``Doxyfile``. Note that you can rename the @@ -594,7 +595,8 @@ aliases however you want to fit your naming scheme. "m_enddiv=" \ "m_span{1}=" \ "m_endspan=" \ - "m_class{1}=" + "m_class{1}=" \ + "m_footernavigation=" With ``@m_div`` and ``@m_span`` it's possible to wrap individual paragraphs or inline text in :html:`
` / :html:`` and add CSS classes to them. @@ -645,6 +647,12 @@ formula. Example usage: See the red :math-danger:`\Sigma` character. +The ``@m_footernavigation`` command is similar to ``@tableofcontents``, but +across pages --- if a page is a subpage of some other page and this command is +present in page detailed description, it will cause the footer of the rendered +page to contain a link to previous, parent and next page according to defined +page order. + `Customizing the template`_ =========================== @@ -764,7 +772,9 @@ Property Description :py:`compound.has_template_details` If there is a detailed documentation of template parameters :py:`compound.sections` Sections of detailed description. See - `Section properties`_ for details. + `Navigation properties`_ for details. +:py:`compound.footer_navigation` Footer navigation of a page. See + `Navigation properties`_ for details. :py:`compound.brief` Brief description. Can be empty. [1]_ :py:`compound.description` Detailed description. Can be empty. [2]_ :py:`compound.dirs` List of directories in this compound. @@ -858,8 +868,8 @@ Property Description result will be saved ======================================= ======================================= -`Section properties`_ -````````````````````` +`Navigation properties`_ +```````````````````````` The :py:`compound.sections` property defines a Table of Contents for given detailed description. It's a list of :py:`(id, title, children)` tuples, where @@ -868,6 +878,13 @@ a recursive list of nested sections. If the list is empty, given detailed description either has no sections or the TOC was not explicitly requested via ``@tableofcontents`` in case of pages. +The :py:`compound.footer_navigation` property defines footer navigation +requested by the ``@m_footernavigation`` `theme-specific command <#theme-specific-commands>`_. +If available, it's a tuple of :py:`(prev, up, next)` where each item is a tuple +of :py:`(url, title)` for a page that's either previous in the defined order, +one level up or next. For starting/ending page the :py:`prev`/:py:`next` is +:py:`None`. + `Directory properties`_ ``````````````````````` diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 261a2442..9887dc2e 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -141,6 +141,7 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. out.params = {} out.return_value = None out.add_css_class = None + out.footer_navigation = False # DOXYGEN PATCHING 1/4 # @@ -412,6 +413,9 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. # resetting here explicitly. add_css_class = parsed.add_css_class + # Bubble up also the footer navigation + if parsed.footer_navigation: out.footer_navigation = True + # Assert we didn't miss anything important assert not parsed.section @@ -601,6 +605,10 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. else: add_inline_css_class = i.attrib['{http://mcss.mosra.cz/doxygen/}class'] + # Enabling footer navigation in a page + elif i.tag == '{http://mcss.mosra.cz/doxygen/}footernavigation': + out.footer_navigation = True + # Either block or inline elif i.tag == 'programlisting': assert element.tag == 'para' # is inside a paragraph :/ @@ -856,7 +864,7 @@ def parse_toplevel_desc(state: State, element: ET.Element): assert not parsed.return_value if parsed.params: logging.warning("Use @tparam instead of @param for documenting class templates, @param is ignored") - return (parsed.parsed, parsed.templates, parsed.section[2] if parsed.section else '') + return (parsed.parsed, parsed.templates, parsed.section[2] if parsed.section else '', parsed.footer_navigation) def parse_typedef_desc(state: State, element: ET.Element): # Verify that we didn't ignore any important info by accident @@ -1224,7 +1232,8 @@ def parse_xml(state: State, xml: str): compound.has_template_details = False compound.templates = None compound.brief = parse_desc(state, compounddef.find('briefdescription')) - compound.description, templates, compound.sections = parse_toplevel_desc(state, compounddef.find('detaileddescription')) + compound.description, templates, compound.sections, footer_navigation = parse_toplevel_desc(state, compounddef.find('detaileddescription')) + compound.footer_navigation = None compound.dirs = [] compound.files = [] compound.namespaces = [] @@ -1271,6 +1280,30 @@ def parse_xml(state: State, xml: str): if compounddef.find('tableofcontents') is None: compound.sections = [] + # Enable footer navigation, if requested + if footer_navigation: + up = state.compounds[compound.id].parent + + # Go through all parent children and + if up: + up = state.compounds[up] + + prev = None + next = None + prev_child = None + for child in up.children: + if child == compound.id: + if prev_child: prev = state.compounds[prev_child] + elif prev_child == compound.id: + next = state.compounds[child] + break + + prev_child = child + + compound.footer_navigation = ((prev.url, prev.name) if prev else None, + (up.url, up.name), + (next.url, next.name) if next else None) + if compound.brief: # Remove duplicated brief in pages. Doxygen sometimes adds a period # at the end, try without it also. diff --git a/doxygen/templates/base.html b/doxygen/templates/base.html index d7d632fa..161c17ca 100644 --- a/doxygen/templates/base.html +++ b/doxygen/templates/base.html @@ -6,6 +6,8 @@ {% for css in HTML_EXTRA_STYLESHEET %} {% endfor %} + {% block header_links %} + {% endblock %} diff --git a/doxygen/templates/page.html b/doxygen/templates/page.html index fc227a0f..a4c7ebc0 100644 --- a/doxygen/templates/page.html +++ b/doxygen/templates/page.html @@ -3,6 +3,15 @@ {% 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 %} +{% block header_links %} +{% if compound.footer_navigation and compound.footer_navigation[0] %} + +{% endif %} +{% if compound.footer_navigation and compound.footer_navigation[2] %} + +{% endif %} +{% endblock %} + {% block main %}

{% for name, target in compound.breadcrumb[:-1] %} @@ -32,7 +41,10 @@

{% endif %} -{% if compound.description %} + {% if compound.description %} {{ compound.description }} -{% endif %} + {% endif %} + {% if compound.footer_navigation %} +
{% if compound.footer_navigation[0] %}« {{ compound.footer_navigation[0][1] }} | {% endif %}{{ compound.footer_navigation[1][1] }}{% if compound.footer_navigation[2] %} | {{ compound.footer_navigation[2][1] }} »{% endif %}
+ {% endif %} {% endblock %} diff --git a/doxygen/test/contents_custom/Doxyfile b/doxygen/test/contents_custom/Doxyfile index a902bd3f..afc65d51 100644 --- a/doxygen/test/contents_custom/Doxyfile +++ b/doxygen/test/contents_custom/Doxyfile @@ -12,4 +12,5 @@ ALIASES = \ "m_enddiv=@xmlonly@endxmlonly" \ "m_span{1}=@xmlonly@endxmlonly" \ "m_endspan=@xmlonly@endxmlonly" \ - "m_class{1}=@xmlonly@endxmlonly" + "m_class{1}=@xmlonly@endxmlonly" \ + "m_footernavigation=@xmlonly@endxmlonly" diff --git a/doxygen/test/contents_custom/input.dox b/doxygen/test/contents_custom/input.dox index 6c9951f6..2ef19b7c 100644 --- a/doxygen/test/contents_custom/input.dox +++ b/doxygen/test/contents_custom/input.dox @@ -48,6 +48,8 @@ An unstyled list: /** @page math Math +@m_footernavigation + A green formula: @m_class{m-success} @@ -58,4 +60,17 @@ A green formula: A yellow @m_class{m-warning} @f$ \Sigma @f$ inline formula. +- @subpage subpage1 First subpage +- @subpage subpage2 Second subpage + +*/ + +/** @page subpage1 First subpage + +@m_footernavigation +*/ + +/** @page subpage2 Second subpage + +@m_footernavigation */ diff --git a/doxygen/test/contents_custom/math.html b/doxygen/test/contents_custom/math.html index 7dcbc588..3f064b6b 100644 --- a/doxygen/test/contents_custom/math.html +++ b/doxygen/test/contents_custom/math.html @@ -61,7 +61,7 @@ $ \Sigma $ - inline formula.

+ inline formula.

@@ -76,4 +76,4 @@ $ \Sigma $ - \ No newline at end of file + diff --git a/doxygen/test/contents_custom/subpage1.html b/doxygen/test/contents_custom/subpage1.html new file mode 100644 index 00000000..a41c7cfe --- /dev/null +++ b/doxygen/test/contents_custom/subpage1.html @@ -0,0 +1,57 @@ + + + + + Math » First subpage | My Project + + + + + + + +
+
+ + + diff --git a/doxygen/test/contents_custom/subpage2.html b/doxygen/test/contents_custom/subpage2.html new file mode 100644 index 00000000..163982df --- /dev/null +++ b/doxygen/test/contents_custom/subpage2.html @@ -0,0 +1,57 @@ + + + + + Math » Second subpage | My Project + + + + + + + +
+
+ + + diff --git a/doxygen/test/test_contents.py b/doxygen/test/test_contents.py index 704b295f..8c5f4059 100644 --- a/doxygen/test/test_contents.py +++ b/doxygen/test/test_contents.py @@ -139,3 +139,8 @@ class Custom(IntegrationTestCase): def test_math(self): self.run_dox2html5(wildcard='math.xml') self.assertEqual(*self.actual_expected_contents('math.html')) + + def test_footer_navigation(self): + self.run_dox2html5(wildcard='subpage*.xml') + self.assertEqual(*self.actual_expected_contents('subpage1.html')) + self.assertEqual(*self.actual_expected_contents('subpage2.html'))