documentation/doxygen: added support for C++20 concepts

documentation/templates/doxygen/annotated.html

@@ -5,14 +5,14 @@
         <h1>Classes</h1>
         <ul class="m-doc">
           {% for i in index.symbols recursive %}
-          {% if i.children %}
+          {% if i.children and i.has_class_descendents %}
           <li class="m-doc-collapsible{% if loop.depth > CLASS_INDEX_EXPAND_LEVELS or (i.kind != 'namespace' and not CLASS_INDEX_EXPAND_INNER) %} collapsed{% endif %}">
             <a href="#" onclick="return toggle(this)">{{ i.kind }}</a> <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a>{% if i.is_inline %} <span class="m-label m-flat m-info">inline</span>{% endif %}{% if i.is_final %} <span class="m-label m-flat m-warning">final</span>{% endif %}{% if i.deprecated %} <span class="m-label m-danger">{{ i.deprecated }}</span>{% endif %}{% if i.since %} {{ i.since }}{% endif %} <span class="m-doc">{{ i.brief }}</span>
             <ul class="m-doc">
 {{ loop(i.children)|rtrim|indent(4, true) }}
             </ul>
           </li>
-          {% else %}
+          {% elif i.kind in ('class', 'struct', 'union') %}
           <li>{{ i.kind }} <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a>{% if i.is_inline %} <span class="m-label m-flat m-info">inline</span>{% endif %}{% if i.is_final %} <span class="m-label m-flat m-warning">final</span>{% endif %}{% if i.deprecated %} <span class="m-label m-danger">{{ i.deprecated }}</span>{% endif %}{% if i.since %} {{ i.since }}{% endif %} <span class="m-doc">{{ i.brief }}</span></li>
           {% endif %}
           {% endfor %}

documentation/templates/doxygen/base-class-reference.html

@@ -1,6 +1,7 @@
 {% extends 'base.html' %}
 
 {% macro entry_class(class) %}{% include 'entry-class.html' %}{% endmacro %}
+{% macro entry_concept(concept) %}{% include 'entry-concept.html' %}{% endmacro %}
 {% macro entry_typedef(typedef, mark_nonpublic=False) %}{% include 'entry-typedef.html' %}{% endmacro %}
 {% macro entry_enum(enum, mark_nonpublic=False) %}{% include 'entry-enum.html' %}{% endmacro %}
 {% macro entry_func(func, mark_nonpublic=False) %}{% include 'entry-func.html' %}{% endmacro %}
@@ -166,6 +167,8 @@ <h2><a href="#pub-types">Public types</a></h2>
             {% for kind, type in compound.public_types %}
             {% if kind == 'class' %}
 {{ entry_class(type) }}
+            {% elif kind == 'concept' %}
+{{ entry_concept(type) }}
             {% elif kind == 'enum' %}
 {{ entry_enum(type) }}
             {% elif kind == 'typedef' %}
@@ -252,6 +255,8 @@ <h2><a href="#pro-types">Protected types</a></h2>
             {% for kind, type in compound.protected_types %}
             {% if kind == 'class' %}
 {{ entry_class(type) }}
+            {% elif kind == 'concept' %}
+{{ entry_concept(type) }}
             {% elif kind == 'enum' %}
 {{ entry_enum(type) }}
             {% elif kind == 'typedef' %}

documentation/templates/doxygen/base-reference.html

@@ -7,6 +7,7 @@
 {% macro entry_file(file) %}{% include 'entry-file.html' %}{% endmacro %}
 {% macro entry_namespace(namespace) %}{% include 'entry-namespace.html' %}{% endmacro %}
 {% macro entry_class(class) %}{% include 'entry-class.html' %}{% endmacro %}
+{% macro entry_concept(concept) %}{% include 'entry-concept.html' %}{% endmacro %}
 {% macro entry_enum(enum) %}{% include 'entry-enum.html' %}{% endmacro %}
 {% macro entry_typedef(typedef) %}{% include 'entry-typedef.html' %}{% endmacro %}
 {% macro entry_func(func) %}{% include 'entry-func.html' %}{% endmacro %}
@@ -25,7 +26,7 @@
         {% if compound.brief %}
         <p>{{ compound.brief }}</p>
         {% endif %}
-        {% if compound.sections or compound.modules or compound.dirs or compound.files or compound.namespaces or compound.classes or compound.typedefs or compound.funcs or compound.vars or compound.defines or compound.groups %}
+        {% if compound.sections or compound.modules or compound.dirs or compound.files or compound.namespaces or compound.classes or compound.concepts or compound.typedefs or compound.funcs or compound.vars or compound.defines or compound.groups %}
         <nav class="m-block m-default">
           <h3>Contents</h3>
           <ul>
@@ -41,7 +42,7 @@ <h3>Contents</h3>
             <li><a href="#{{ id }}">{{ name }}</a></li>
             {% endif %}
             {% endfor %}
-            {% if compound.modules or compound.dirs or compound.files or compound.namespaces or compound.classes or compound.typedefs or compound.funcs or compound.vars or compound.defines or compound.groups %}
+            {% if compound.modules or compound.dirs or compound.files or compound.namespaces or compound.classes or compound.concepts or compound.typedefs or compound.funcs or compound.vars or compound.defines or compound.groups %}
             <li>
               Reference
               <ul>
@@ -60,6 +61,9 @@ <h3>Contents</h3>
                 {% if compound.classes %}
                 <li><a href="#nested-classes">Classes</a></li>
                 {% endif %}
+                {% if compound.concepts %}
+                <li><a href="#nested-concepts">Concepts</a></li>
+                {% endif %}
                 {% if compound.enums %}
                 <li><a href="#enum-members">Enums</a></li>
                 {% endif %}
@@ -137,6 +141,16 @@ <h2><a href="#nested-classes">Classes</a></h2>
           </dl>
         </section>
         {% endif %}
+        {% if compound.concepts %}
+        <section id="nested-concepts">
+          <h2><a href="#nested-concepts">Concepts</a></h2>
+          <dl class="m-doc">
+            {% for concept in compound.concepts %}
+{{ entry_concept(concept) }}
+            {% endfor %}
+          </dl>
+        </section>
+        {% endif %}
         {% if compound.enums %}
         <section id="enum-members">
           <h2><a href="#enum-members">Enums</a></h2>
@@ -199,6 +213,8 @@ <h2><a href="#{{ group.id }}">{{ group.name }}</a></h2>
 {{ entry_namespace(member) }}
             {% elif kind == 'class' %}
 {{ entry_class(member) }}
+            {% elif kind == 'concept' %}
+{{ entry_concept(member) }}
             {% elif kind == 'enum' %}
 {{ entry_enum(member) }}
             {% elif kind == 'typedef' %}

documentation/templates/doxygen/concept.html

@@ -0,0 +1 @@
+{% extends 'base-class-reference.html' %}

documentation/templates/doxygen/concepts.html

@@ -0,0 +1,21 @@
+{% set navbar_current = 'concepts' %}
+{% extends 'base-index.html' %}
+
+{% block main %}
+        <h1>Concepts</h1>
+        <ul class="m-doc">
+          {% for i in index.symbols recursive %}
+          {% if i.children and i.has_concept_descendents %}
+          <li class="m-doc-collapsible{% if loop.depth > CLASS_INDEX_EXPAND_LEVELS or (i.kind != 'namespace' and not CLASS_INDEX_EXPAND_INNER) %} collapsed{% endif %}">
+            <a href="#" onclick="return toggle(this)">{{ i.kind }}</a> <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a>{% if i.deprecated %} <span class="m-label m-danger">{{ i.deprecated }}</span>{% endif %}{% if i.since %} {{ i.since }}{% endif %} <span class="m-doc">{{ i.brief }}</span>
+            <ul class="m-doc">
+{{ loop(i.children)|rtrim|indent(4, true) }}
+            </ul>
+          </li>
+          {% elif i.kind == 'concept' %}
+          <li>{{ i.kind }} <a href="{{ i.url }}" class="m-doc">{{ i.name }}</a>{% if i.deprecated %} <span class="m-label m-danger">{{ i.deprecated }}</span>{% endif %}{% if i.since %} {{ i.since }}{% endif %} <span class="m-doc">{{ i.brief }}</span></li>
+          {% endif %}
+          {% endfor %}
+        </ul>
+{{ super() -}}
+{% endblock %}

documentation/templates/doxygen/details-var.html

@@ -15,7 +15,7 @@ <h3>
                 {% endif %}
               </div>
               {% endif %}
-              {%+ if var.is_static %}static {% endif %}{{ var.type }} {{ prefix }}<a href="#{{ var.id }}" class="m-doc-self">{{ var.name }}</a>{% if var.is_protected %} <span class="m-label m-warning">protected</span>{% endif %}{% if var.is_constexpr %} <span class="m-label m-primary">constexpr</span>{% endif %}{% if var.since %} {{ var.since }}{% endif %}
+              {%+ if var.is_static %}static {% endif %}{{ var.type }} {{ prefix }}<a href="#{{ var.id }}" class="m-doc-self">{{ var.name }}</a>{% if var.is_protected %} <span class="m-label m-warning">protected</span>{% endif %}{% if var.is_constexpr %} <span class="m-label m-primary">constexpr</span>{% endif %}{% if var.is_constinit %} <span class="m-label m-primary">constinit</span>{% endif %}{% if var.since %} {{ var.since }}{% endif %}
               {# the empty line needs to be here to prevent the lines from merging #}
 
               {% if var.include and compound.templates == None and var.templates == None %}

documentation/templates/doxygen/entry-concept.html

@@ -0,0 +1,10 @@
+            <dt>
+              {% if concept.templates != None %}
+              {% set j = joiner(', ') %}
+              <div class="m-doc-template">template&lt;{% for t in concept.templates %}{{ j() }}{{ t.type }}{% if t.name %} {{ t.name }}{% endif %}{% if t.default %} = {{ t.default }}{% endif %}{% endfor %}&gt;</div>
+              {% endif %}
+              {{ concept.kind }} <a href="{{ concept.url }}" class="m-doc">{{ concept.name }}</a>{% if concept.is_protected %} <span class="m-label m-flat m-warning">protected</span>{% endif %}{% if concept.deprecated %} <span class="m-label m-danger">{{ concept.deprecated }}</span>{% endif %}{% if concept.since %} {{ concept.since }}{% endif %}
+
+              {# the empty line is above to fix spacing #}
+            </dt>
+            <dd>{{ concept.brief }}</dd>

documentation/test_doxygen/compound_listing/annotated.html

@@ -37,7 +37,6 @@
       <div class="m-col-l-10 m-push-l-1">
         <h1>Classes</h1>
         <ul class="m-doc">
-          <li>namespace <a href="namespaceAnother.html" class="m-doc">Another</a> <span class="m-doc">Another namespace.</span></li>
           <li class="m-doc-collapsible">
             <a href="#" onclick="return toggle(this)">namespace</a> <a href="namespaceRoot.html" class="m-doc">Root</a> <span class="m-doc">Root namespace.</span>
             <ul class="m-doc">

documentation/test_doxygen/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html

@@ -99,7 +99,7 @@ <h2><a href="#pub-types">Public types</a></h2>
           <h2><a href="#pub-static-attribs">Public static variables</a></h2>
           <dl class="m-doc">
             <dt id="a912d8f1390853f90e0a9f19ec98771e6">
-              static static int <a href="#a912d8f1390853f90e0a9f19ec98771e6" class="m-doc-self">Size</a> <span class="m-label m-flat m-primary">constexpr</span>
+              static int <a href="#a912d8f1390853f90e0a9f19ec98771e6" class="m-doc-self">Size</a> <span class="m-label m-flat m-primary">constexpr</span>
             </dt>
             <dd>A public static var.</dd>
           </dl>

documentation/test_doxygen/test_search.py

@@ -32,6 +32,9 @@
 from doxygen import EntryType
 from _search import pretty_print, searchdata_filename
 
+from distutils.version import LooseVersion
+from . import doxygen_version
+
 from test_doxygen import IntegrationTestCase
 
 class Search(IntegrationTestCase):
@@ -42,7 +45,7 @@ def test(self):
             serialized = f.read()
             search_data_pretty = pretty_print(serialized, entryTypeClass=EntryType)[0]
         #print(search_data_pretty)
-        self.assertEqual(len(serialized), 4841)
+        self.assertEqual(len(serialized), 4850)
         self.assertEqual(search_data_pretty, """
 53 symbols
 deprecated_macro [0]
@@ -223,15 +226,16 @@ class [20]
 (EntryType.DEFINE, CssClass.INFO, 'define'),
 (EntryType.ENUM, CssClass.PRIMARY, 'enum'),
 (EntryType.ENUM_VALUE, CssClass.DEFAULT, 'enum val'),
-(EntryType.VAR, CssClass.DEFAULT, 'var')
+(EntryType.VAR, CssClass.DEFAULT, 'var'),
+(EntryType.CONCEPT, CssClass.PRIMARY, 'concept')
 """.strip())
 
     def test_byte_sizes(self):
         for config, bytes, size in [
-            ('SEARCH_RESULT_ID_BYTES', 3, 4959),
-            ('SEARCH_RESULT_ID_BYTES', 4, 5077),
-            ('SEARCH_FILE_OFFSET_BYTES', 4, 5302),
-            ('SEARCH_NAME_SIZE_BYTES', 2, 4893)
+            ('SEARCH_RESULT_ID_BYTES', 3, 4968),
+            ('SEARCH_RESULT_ID_BYTES', 4, 5086),
+            ('SEARCH_FILE_OFFSET_BYTES', 4, 5311),
+            ('SEARCH_NAME_SIZE_BYTES', 2, 4902)
         ]:
             with self.subTest(config=config, bytes=bytes, size=size):
                 self.run_doxygen(index_pages=[], wildcard='*.xml', config={
@@ -249,8 +253,12 @@ def test(self):
         with open(os.path.join(self.path, 'html', searchdata_filename.format(search_filename_prefix='searchdata')), 'rb') as f:
             serialized = f.read()
             search_data_pretty = pretty_print(serialized, entryTypeClass=EntryType)[0]
+            if LooseVersion(doxygen_version()) >= LooseVersion("1.9.2"):
+                # Doxygen's hash ID generation differs in some circumstances from 1.9.2 onward;
+                # this ugly hack allows the test to pass in either case
+                search_data_pretty = search_data_pretty.replace('a2a7357e0cfd97ec186a2a4e92732611c', 'a1e9a11887275938ef5541070955c9d9c')
         #print(search_data_pretty)
-        self.assertEqual(len(serialized), 478)
+        self.assertEqual(len(serialized), 487)
         # The parameters get cut off with an ellipsis
         self.assertEqual(search_data_pretty, """
 2 symbols
@@ -278,7 +286,8 @@ def test(self):
 (EntryType.DEFINE, CssClass.INFO, 'define'),
 (EntryType.ENUM, CssClass.PRIMARY, 'enum'),
 (EntryType.ENUM_VALUE, CssClass.DEFAULT, 'enum val'),
-(EntryType.VAR, CssClass.DEFAULT, 'var')
+(EntryType.VAR, CssClass.DEFAULT, 'var'),
+(EntryType.CONCEPT, CssClass.PRIMARY, 'concept')
 """.strip())
 
 if __name__ == '__main__': # pragma: no cover