From: Vladimír Vondruš Date: Mon, 8 Jun 2020 22:15:10 +0000 (+0200) Subject: documentation/doxygen: parse inline namespaces. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=eacca3e7ba1d58cb529a86462f2a02591fdb3437;p=blog.git documentation/doxygen: parse inline namespaces. --- diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst index 9181f38b..7329c876 100644 --- a/doc/documentation/doxygen.rst +++ b/doc/documentation/doxygen.rst @@ -867,6 +867,18 @@ and you have to enable the :ini:`EXTRACT_PRIV_VIRTUAL` Doxyfile option: with :gh:`doxygen/doxygen#6729` integrated, the 1.8.15 release does not have this option yet. +`Inline namespaces`_ +-------------------- + +:cpp:`inline namespace`\ s are marked as such in class/namespace index pages, +namespace documentation pages and nested namespace lists. Doxygen additionally +flattens those, so their contents appear in the parent namespace as well. + +.. note-warning:: Doxygen patches + + This feature requires :gh:`doxygen/doxygen#7828` to work (not merged to + Doxygen master yet). + `Include files`_ ---------------- @@ -1669,6 +1681,8 @@ Property Description :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.is_inline` Whether the namespace is :cpp:`inline`. + Set only for namespaces. :py:`compound.is_final` Whether the class is :cpp:`final`. Set only for classes. :py:`compound.deprecated` Deprecation status [7]_ @@ -1894,6 +1908,7 @@ Property Description :py:`namespace.deprecated` Deprecation status [7]_ :py:`namespace.since` Since which version the namespace is available [8]_ +:py:`namespace.is_inline` Whether this is an :cpp:`inline` namespace =============================== =============================================== `Class properties`_ @@ -2327,6 +2342,8 @@ Property Description :py:`i.brief` Brief documentation :py:`i.deprecated` Deprecation status [7]_ :py:`i.since` Since which version the entry is available [8]_ +:py:`i.is_inline` Whether this is an :cpp:`inline` namespace. Set + only for namespaces. :py:`i.is_final` Whether the class is :cpp:`final`. Set only for classes. :py:`i.has_nestable_children` If the list has nestable children (i.e., dirs diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 21b8ee32..46475837 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -2227,6 +2227,10 @@ def extract_metadata(state: State, xml): compound.deprecated = 'deprecated' break + # Inline namespaces + if compound.kind == 'namespace': + compound.is_inline = compounddef.attrib.get('inline') == 'yes' + # Final classes if compound.kind in ['struct', 'class', 'union']: compound.is_final = compounddef.attrib.get('final') == 'yes' @@ -2539,6 +2543,10 @@ def parse_xml(state: State, xml: str): else: state.current_prefix = [] + # Inline namespaces + if compound.kind == 'namespace': + compound.is_inline = compounddef.attrib.get('inline') == 'yes' + # Final classes if compound.kind in ['struct', 'class', 'union']: compound.is_final = compounddef.attrib.get('final') == 'yes' @@ -2659,6 +2667,7 @@ def parse_xml(state: State, xml: str): namespace.brief = symbol.brief namespace.deprecated = symbol.deprecated namespace.since = symbol.since + namespace.is_inline = compounddef_child.attrib.get('inline') == 'yes' compound.namespaces += [namespace] else: @@ -3253,6 +3262,8 @@ def parse_index_xml(state: State, xml): entry.deprecated = compound.deprecated entry.since = compound.since entry.has_nestable_children = False + if compound.kind == 'namespace': + entry.is_inline = compound.is_inline if compound.kind in ['class', 'struct', 'union']: entry.is_final = compound.is_final diff --git a/documentation/templates/doxygen/annotated.html b/documentation/templates/doxygen/annotated.html index c8ed0a78..50fa77b9 100644 --- a/documentation/templates/doxygen/annotated.html +++ b/documentation/templates/doxygen/annotated.html @@ -7,13 +7,13 @@ {% for i in index.symbols recursive %} {% if i.children %}
  • - {{ i.kind }} {{ i.name }}{% if i.is_final %} final{% endif %}{% if i.deprecated %} {{ i.deprecated }}{% endif %}{% if i.since %} {{ i.since }}{% endif %} {{ i.brief }} + {{ i.kind }} {{ i.name }}{% if i.is_inline %} inline{% endif %}{% if i.is_final %} final{% endif %}{% if i.deprecated %} {{ i.deprecated }}{% endif %}{% if i.since %} {{ i.since }}{% endif %} {{ i.brief }}
    • {% else %} -
  • {{ i.kind }} {{ i.name }}{% if i.is_final %} final{% endif %}{% if i.deprecated %} {{ i.deprecated }}{% endif %}{% if i.since %} {{ i.since }}{% endif %} {{ i.brief }}
    • +
  • {{ i.kind }} {{ i.name }}{% if i.is_inline %} inline{% endif %}{% if i.is_final %} final{% endif %}{% if i.deprecated %} {{ i.deprecated }}{% endif %}{% if i.since %} {{ i.since }}{% endif %} {{ i.brief }}
    • {% endif %} {% endfor %} diff --git a/documentation/templates/doxygen/entry-namespace.html b/documentation/templates/doxygen/entry-namespace.html index 9e90087b..e0fb9ee7 100644 --- a/documentation/templates/doxygen/entry-namespace.html +++ b/documentation/templates/doxygen/entry-namespace.html @@ -1,2 +1,2 @@ -
    namespace {{ namespace.name }}{% if namespace.deprecated %} {{ namespace.deprecated }}{% endif %}{% if namespace.since %} {{ namespace.since }}{% endif %}
    +
    namespace {{ namespace.name }}{% if namespace.is_inline %} inline{% endif %}{% if namespace.deprecated %} {{ namespace.deprecated }}{% endif %}{% if namespace.since %} {{ namespace.since }}{% endif %}
    {{ namespace.brief }}
    diff --git a/documentation/templates/doxygen/namespace.html b/documentation/templates/doxygen/namespace.html index 9cab47fc..267d4399 100644 --- a/documentation/templates/doxygen/namespace.html +++ b/documentation/templates/doxygen/namespace.html @@ -4,7 +4,7 @@ {% block header %}

    - {%+ for name, target in compound.breadcrumb[:-1] %}{{ name }}::{% endfor %}{{ compound.breadcrumb[-1][0] }} namespace{% if compound.since %} {{ compound.since }}{% endif %} + {%+ for name, target in compound.breadcrumb[:-1] %}{{ name }}::{% endfor %}{{ compound.breadcrumb[-1][0] }} namespace{% if compound.is_inline %} inline{% endif %}{% if compound.since %} {{ compound.since }}{% endif %} {# need an explicit space here otherwise the newline gets removed #} {% if compound.include %} diff --git a/documentation/templates/doxygen/namespaces.html b/documentation/templates/doxygen/namespaces.html index 5ff416bf..ca874823 100644 --- a/documentation/templates/doxygen/namespaces.html +++ b/documentation/templates/doxygen/namespaces.html @@ -7,13 +7,13 @@ {% for i in index.symbols|selectattr('kind', 'equalto', 'namespace') recursive %} {% if i.has_nestable_children %}
  • - {{ i.kind }} {{ i.name }}{% if i.deprecated %} {{ i.deprecated }}{% endif %}{% if i.since %} {{ i.since }}{% endif %} {{ i.brief }} + {{ i.kind }} {{ i.name }}{% if i.is_inline %} inline{% endif %}{% if i.deprecated %} {{ i.deprecated }}{% endif %}{% if i.since %} {{ i.since }}{% endif %} {{ i.brief }}
      {{ loop(i.children|selectattr('kind', 'equalto', 'namespace'))|rtrim|indent(4, true) }}
    • {% else %} -
  • {{ i.kind }} {{ i.name }}{% if i.deprecated %} {{ i.deprecated }}{% endif %}{% if i.since %} {{ i.since }}{% endif %} {{ i.brief }}
    • +
  • {{ i.kind }} {{ i.name }}{% if i.is_inline %} inline{% endif %}{% if i.deprecated %} {{ i.deprecated }}{% endif %}{% if i.since %} {{ i.since }}{% endif %} {{ i.brief }}
    • {% endif %} {% endfor %} diff --git a/documentation/test_doxygen/compound_inline_namespace/Doxyfile b/documentation/test_doxygen/compound_inline_namespace/Doxyfile new file mode 100644 index 00000000..9752e60f --- /dev/null +++ b/documentation/test_doxygen/compound_inline_namespace/Doxyfile @@ -0,0 +1,15 @@ +INPUT = File.h +QUIET = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_PROGRAMLISTING = NO +CASE_SENSE_NAMES = YES + +##! M_PAGE_FINE_PRINT = +##! M_THEME_COLOR = +##! M_FAVICON = +##! M_LINKS_NAVBAR1 = +##! M_LINKS_NAVBAR2 = +##! M_SEARCH_DISABLED = YES +##! M_CLASS_TREE_EXPAND_LEVELS = 3 diff --git a/documentation/test_doxygen/compound_inline_namespace/File.h b/documentation/test_doxygen/compound_inline_namespace/File.h new file mode 100644 index 00000000..258dbcec --- /dev/null +++ b/documentation/test_doxygen/compound_inline_namespace/File.h @@ -0,0 +1,15 @@ +/** @brief A namespace */ +namespace Foo { + +/** @brief An inline nested namespace */ +inline namespace Bar { + +/** @brief Another inline namespace */ +inline namespace Baz {} + +} + +/** @brief A thing */ +struct Thing {}; + +} diff --git a/documentation/test_doxygen/compound_inline_namespace/annotated.html b/documentation/test_doxygen/compound_inline_namespace/annotated.html new file mode 100644 index 00000000..dbf61daa --- /dev/null +++ b/documentation/test_doxygen/compound_inline_namespace/annotated.html @@ -0,0 +1,58 @@ + + + + + My Project + + + + + +
    +
    +
    +
    +
    +

    Classes

    +
      +
    • + namespace Foo A namespace. +
        +
      • + namespace Bar inline An inline nested namespace. +
          +
        • namespace Baz inline Another inline namespace.
          • +
        +
        • +
      • struct Thing A thing.
        • +
      +
      • +
    + +
    +
    +
    +
    + + diff --git a/documentation/test_doxygen/compound_inline_namespace/namespaceFoo_1_1Bar.html b/documentation/test_doxygen/compound_inline_namespace/namespaceFoo_1_1Bar.html new file mode 100644 index 00000000..977f05fd --- /dev/null +++ b/documentation/test_doxygen/compound_inline_namespace/namespaceFoo_1_1Bar.html @@ -0,0 +1,49 @@ + + + + + Foo::Bar namespace | My Project + + + + + +
    +
    +
    +
    +
    +

    + Foo::Bar namespace inline +

    +

    An inline nested namespace.

    +
    +

    Contents

    + +
    +
    +

    Namespaces

    +
    +
    namespace Baz inline
    +
    Another inline namespace.
    +
    +
    +
    +
    +
    +
    + + diff --git a/documentation/test_doxygen/compound_inline_namespace/namespaces.html b/documentation/test_doxygen/compound_inline_namespace/namespaces.html new file mode 100644 index 00000000..85a848a5 --- /dev/null +++ b/documentation/test_doxygen/compound_inline_namespace/namespaces.html @@ -0,0 +1,57 @@ + + + + + My Project + + + + + +
    +
    +
    +
    +
    +

    Namespaces

    +
      +
    • + namespace Foo A namespace. +
        +
      • + namespace Bar inline An inline nested namespace. +
          +
        • namespace Baz inline Another inline namespace.
          • +
        +
        • +
      +
      • +
    + +
    +
    +
    +
    + + diff --git a/documentation/test_doxygen/test_compound.py b/documentation/test_doxygen/test_compound.py index efcd7d1b..97421bd6 100644 --- a/documentation/test_doxygen/test_compound.py +++ b/documentation/test_doxygen/test_compound.py @@ -319,3 +319,15 @@ class BaseTemplateClasses(IntegrationTestCase): def test(self): self.run_doxygen(wildcard='*.xml') self.assertEqual(*self.actual_expected_contents('structNamespace_1_1MyClass.html')) + +class InlineNamespace(IntegrationTestCase): + def test(self): + self.run_doxygen(wildcard='*.xml') + + with open(os.path.join(self.path, 'xml/namespaceFoo_1_1Bar.xml')) as f: + if 'kind="namespace" inline="yes"' not in f.read(): + self.skipTest("Doxygen doesn't support inline namespaces here") + + self.assertEqual(*self.actual_expected_contents('namespaceFoo_1_1Bar.html')) + self.assertEqual(*self.actual_expected_contents('annotated.html')) + self.assertEqual(*self.actual_expected_contents('namespaces.html'))