documentation/doxygen: support styling <dl> with CSS classes.

So I can make my own footnotes. Finally I got to know what kind of
markup is abused for the autogenerated TODO lists.

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 8708ed86db67bfbf973902ce09659d9292496603..2d5a6f9aa9c27fe749815de9d6f636d54dfd9778 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -1033,7 +1033,14 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
         elif i.tag == 'variablelist':
             assert element.tag in ['para', '{http://mcss.mosra.cz/doxygen/}div']
             has_block_elements = True
-            out.parsed += '<dl class="m-doc">'
+            # Usually, <variablelist> is used to format todo lists and other
+            # xrefitems (without being explicitly marked as such, of course),
+            # in which case the styling is provided by the m-doc CSS class. But
+            # if the user explicitly provided a CSS class using @m_class, then
+            # it was probably literal <dl> directly in the markup, used for
+            # example for a footnote list. In that case use the provided class
+            # instead of m-doc.
+            out.parsed += '<dl class="{}">'.format(add_css_class if add_css_class else 'm-doc')
 
             for var in i:
                 if var.tag == 'varlistentry':

diff --git a/documentation/test_doxygen/contents_custom/index.html b/documentation/test_doxygen/contents_custom/index.html
index ace7534a17e30e365c65228027161eda442aa175..164b229fd368b651ec88d2788e4b142bf41ccd8c 100644 (file)
--- a/documentation/test_doxygen/contents_custom/index.html
+++ b/documentation/test_doxygen/contents_custom/index.html
@@ -23,7 +23,7 @@
           My Project
         </h1>
 <div class="m-note m-dim m-text-center">This paragraph <em>is</em> rendered in a dim note, centered.</div><p>This paragraph contains a <span class="m-text m-danger"><em>red</em> text</span> in a normal text flow and then  <strong class="m-text m-em m-small">small strong italics</strong>,   <em class="m-text m-info">blue italics</em> and  <a href="https://mcss.mosra.cz" class="m-text m-big">https:/<wbr />/<wbr />mcss.mosra.cz</a> (big-ass link). A styled page ref:   <a href="math.html" class="m-label m-success">The math page</a>.</p><div class="m-button m-primary"><a href="#"><div class="m-big">A button</div> <div class="m-small"><span class="m-text m-em">with</span>  <strong class="m-text m-em">subtitle</strong></div></a></div><p>A paragraph that is not affected by the inline classes from above.</p><p class="m-text m-strong m-noindent">Bold, non-indented paragraph.</p><p class="m-text m-primary"><strong>Bold text that should not have</strong> the same class as the paragraph.</p><p>A paragraph that doesn&#x27;t have any class applied. Next, a full-width image:</p><img class="m-image m-fullwidth" src="ship-small.jpg" alt="Image" /><figure class="m-figure m-flat"><img src="ship-small.jpg" alt="Image" /><figcaption>A flat figure</figcaption></figure><p>A fullwidth table:</p><table class="m-table m-fullwidth"><thead><tr><th>Table header</th><th>Another</th></tr></thead><tbody><tr><td>Cell</td><td>Another cell</td></tr><tr><td>Next row</td><td>Last.</td></tr></tbody></table><p>An unstyled list:</p><ul class="m-unstyled"><li>First item without a dot</li><li>Second item without a dot</li></ul><aside class="m-block m-info"><h3>A info block with some paragraphs inside</h3><div><p>Hello.</p><p>This is good, finally.</p></div></aside><aside class="m-frame"><h3>Note</h3><p>A note styled as a frame.</p></aside><p>This has to be here otherwise doxygen puts the next <code>@m_class</code> call into the above note. WHAT THE HELL!!!</p><aside class="m-block m-success"><h3><a href="licenses.html#_licenses000001" class="m-doc">Third-party license info</a></h3><p>This package is licensed under MIT. All is good.</p></aside><div class="m-code-figure"><pre class="m-code"><span class="c1">// this is the code</span>
-<span class="n">printf</span><span class="p">(</span><span class="s">&quot;The answer to the universe and everything is %d.&quot;</span><span class="p">,</span> <span class="mi">5</span><span class="o">*</span><span class="mi">9</span><span class="p">)</span></pre><p>The answer to the universe and everything is 42.</p></div>
+<span class="n">printf</span><span class="p">(</span><span class="s">&quot;The answer to the universe and everything is %d.&quot;</span><span class="p">,</span> <span class="mi">5</span><span class="o">*</span><span class="mi">9</span><span class="p">)</span></pre><p>The answer to the universe and everything is 42.</p></div><p>A paragraph containing a footnote  <a href="#note27" class="m-footnote">27</a> reference.</p><dl class="m-footnote"><dt>27.</dt><dd><a name="note27"></a>And a styled footnote, overriding the default styling which is used for TODO pages and other xrefitems, like <a href="licenses.html" class="m-doc">Third-party license info</a>.</dd></dl>
       </div>
     </div>
   </div>

diff --git a/documentation/test_doxygen/contents_custom/input.dox b/documentation/test_doxygen/contents_custom/input.dox
index 42778e153654f158fe29b0751dbbb9d711b1668b..4abd1393727546a77e4877df8b2c5eb70a657a26 100644 (file)
--- a/documentation/test_doxygen/contents_custom/input.dox
+++ b/documentation/test_doxygen/contents_custom/input.dox
@@ -79,6 +79,18 @@ printf("The answer to the universe and everything is %d.", 5*9)
 The answer to the universe and everything is 42.
 @endparblock
 
+A paragraph containing a footnote @m_class{m-footnote} [27](#note27) reference.
+
+@m_class{m-footnote}
+
+<dl>
+<dt>27.</dt>
+<dd>
+@anchor note27
+And a styled footnote, overriding the default styling which is used for
+TODO pages and other xrefitems, like @ref licenses.
+</dd>
+</dl>
 */
 
 /** @page math Math