Skip to content

Commit

Permalink
documentation/doxygen: work around Doxyen stupidly making XMLs useless.
Browse files Browse the repository at this point in the history 
I still hope that particular change can be reverted, but so far it's
just the least possible amount of work to make this tool not hit a
sanity assert.
  • Loading branch information
@mosra
mosra committed Sep 14, 2024
1 parent 9febf02 commit 09ddeeb
Show file tree
Hide file tree
Showing 11 changed files with 745 additions and 10 deletions.
27 changes: 27 additions & 0 deletions documentation/doxygen.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3020,6 +3020,33 @@ def parse_xml(state: State, xml: str):

# Other, grouped in sections
elif compounddef_child.tag == 'sectiondef':
# If grouping is used in the documentation, Doxygen 1.9.7+ no
# longer puts the whole <memberdef> info into file and namespace
# docs, but instead only <member> references, forcing the parsers
# to look for the identifier in other XML files.
#
# The reason for this, as discussed in the linked PR, is because
# some random downstream project failed due to encountering
# duplicate IDs (which are there for file/namespace members also,
# by the way! or for relatedalso members!!). And Doxygen maintainer
# VERY HELPFULLY OFFERED TO CRIPPLE THE XML OUTPUT FOR EVERYONE
# ELSE just to fix that damn thing. Once I calm down I may try to
# convince them to revert this insanity, until then enjoy the
# crappy output.
#
# Also, yes, it may happen that there are combined <memberdef> and
# <member> children. But handling that means adding the same damn
# piece of code, or some dumb filtering, to all branches below,
# just to counter a dumb decision. Nope. Nononono.
is_stupid = False
for memberdef in compounddef_child:
if memberdef.tag == 'member':
logging.warning("{}: sorry, parsing of non-self-contained XML not implemented: due to https://github.com/doxygen/doxygen/issues/8790 the output will not list file / namespace {} members".format(state.current, compounddef_child.attrib['kind']))
is_stupid = True
break
if is_stupid:
continue

if compounddef_child.attrib['kind'] == 'enum':
for memberdef in compounddef_child:
enum = parse_enum(state, memberdef)
Expand Down
105 changes: 105 additions & 0 deletions documentation/test_doxygen/compound_includes/namespaceContained-stupid.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Contained namespace | My Project</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
<link rel="stylesheet" href="m-dark+documentation.compiled.css" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>
<body>
<header><nav id="navigation">
<div class="m-container">
<div class="m-row">
<a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
</div>
</div>
</nav></header>
<main><article>
<div class="m-container m-container-inflatable">
<div class="m-row">
<div class="m-col-l-10 m-push-l-1">
<h1>
Contained <span class="m-thin">namespace</span>
<div class="m-doc-include m-code m-inverted m-text-right"><span class="cp">#include</span> <a class="cpf" href="First_8h.html">&lt;First.h&gt;</a></div>
</h1>
<p>This namespace is contained in a single file.</p>
<nav class="m-block m-default">
<h3>Contents</h3>
<ul>
<li>
Reference
<ul>
<li><a href="#enum-members">Enums</a></li>
<li><a href="#typedef-members">Typedefs</a></li>
<li><a href="#func-members">Functions</a></li>
<li><a href="#var-members">Variables</a></li>
<li><a href="#a-group">A group</a></li>
</ul>
</li>
</ul>
</nav>
<p>So it has only the global include and no per-entry includes, thus also no detailed sections because there&#x27;s only brief. (Unless the includes are disabled globally or the file is not documented.)</p>
<section id="enum-members">
<h2><a href="#enum-members">Enums</a></h2>
<dl class="m-doc">
<dt id="a1e198a456efa4fe54dfc7f1f60e0b5d7">
<span class="m-doc-wrap-bumper">enum <a href="#a1e198a456efa4fe54dfc7f1f60e0b5d7" class="m-doc-self">Enum</a> { </span><span class="m-doc-wrap"> }</span>
</dt>
<dd>An enum.</dd>
</dl>
</section>
<section id="typedef-members">
<h2><a href="#typedef-members">Typedefs</a></h2>
<dl class="m-doc">
<dt id="a011bc16d926b77ad9f172540494d8e84">
using <a href="#a011bc16d926b77ad9f172540494d8e84" class="m-doc-self">Int1</a> = int
</dt>
<dd>A typedef.</dd>
</dl>
</section>
<section id="func-members">
<h2><a href="#func-members">Functions</a></h2>
<dl class="m-doc">
<dt id="a805f49495092c6f2bb1347f50bf2453e">
<span class="m-doc-wrap-bumper">void <a href="#a805f49495092c6f2bb1347f50bf2453e" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">)</span>
</dt>
<dd>A function.</dd>
</dl>
</section>
<section id="var-members">
<h2><a href="#var-members">Variables</a></h2>
<dl class="m-doc">
<dt id="a91e894fe69f4a6c73074f7862ede5503">
const int <a href="#a91e894fe69f4a6c73074f7862ede5503" class="m-doc-self">Var</a> <span class="m-label m-flat m-primary">constexpr</span>
</dt>
<dd>A variable.</dd>
</dl>
</section>
<section id="a-group">
<h2><a href="#a-group">A group</a></h2>
<dl class="m-doc">
<dt id="a11d588fad4de0640556b055558c5fa1d">
<span class="m-doc-wrap-bumper">enum <a href="#a11d588fad4de0640556b055558c5fa1d" class="m-doc-self">Flag</a> { </span><span class="m-doc-wrap"> }</span>
</dt>
<dd>Flag in a group.</dd>
<dt id="ad769587e750dd7cd8de308987f7ccf30">
using <a href="#ad769587e750dd7cd8de308987f7ccf30" class="m-doc-self">Main</a> = void
</dt>
<dd>Alias in a group.</dd>
<dt id="ac65f93520b7abe37daa15a999faa4323">
void* <a href="#ac65f93520b7abe37daa15a999faa4323" class="m-doc-self">variable</a> <span class="m-label m-flat m-primary">constexpr</span>
</dt>
<dd>Variable in a group.</dd>
<dt id="abcad26bce92bd85654aaf9b7effc043b">
<span class="m-doc-wrap-bumper">void <a href="#abcad26bce92bd85654aaf9b7effc043b" class="m-doc-self">bar</a>(</span><span class="m-doc-wrap">)</span>
</dt>
<dd>Function in a group.</dd>
</dl>
</section>
</div>
</div>
</div>
</article></main>
</body>
</html>
104 changes: 104 additions & 0 deletions documentation/test_doxygen/compound_includes_disabled/namespaceContained-stupid.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Contained namespace | My Project</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
<link rel="stylesheet" href="m-dark+documentation.compiled.css" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>
<body>
<header><nav id="navigation">
<div class="m-container">
<div class="m-row">
<a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
</div>
</div>
</nav></header>
<main><article>
<div class="m-container m-container-inflatable">
<div class="m-row">
<div class="m-col-l-10 m-push-l-1">
<h1>
Contained <span class="m-thin">namespace</span>
</h1>
<p>This namespace is contained in a single file.</p>
<nav class="m-block m-default">
<h3>Contents</h3>
<ul>
<li>
Reference
<ul>
<li><a href="#enum-members">Enums</a></li>
<li><a href="#typedef-members">Typedefs</a></li>
<li><a href="#func-members">Functions</a></li>
<li><a href="#var-members">Variables</a></li>
<li><a href="#a-group">A group</a></li>
</ul>
</li>
</ul>
</nav>
<p>So it has only the global include and no per-entry includes, thus also no detailed sections because there&#x27;s only brief. (Unless the includes are disabled globally or the file is not documented.)</p>
<section id="enum-members">
<h2><a href="#enum-members">Enums</a></h2>
<dl class="m-doc">
<dt id="a1e198a456efa4fe54dfc7f1f60e0b5d7">
<span class="m-doc-wrap-bumper">enum <a href="#a1e198a456efa4fe54dfc7f1f60e0b5d7" class="m-doc-self">Enum</a> { </span><span class="m-doc-wrap"> }</span>
</dt>
<dd>An enum.</dd>
</dl>
</section>
<section id="typedef-members">
<h2><a href="#typedef-members">Typedefs</a></h2>
<dl class="m-doc">
<dt id="a011bc16d926b77ad9f172540494d8e84">
using <a href="#a011bc16d926b77ad9f172540494d8e84" class="m-doc-self">Int1</a> = int
</dt>
<dd>A typedef.</dd>
</dl>
</section>
<section id="func-members">
<h2><a href="#func-members">Functions</a></h2>
<dl class="m-doc">
<dt id="a805f49495092c6f2bb1347f50bf2453e">
<span class="m-doc-wrap-bumper">void <a href="#a805f49495092c6f2bb1347f50bf2453e" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">)</span>
</dt>
<dd>A function.</dd>
</dl>
</section>
<section id="var-members">
<h2><a href="#var-members">Variables</a></h2>
<dl class="m-doc">
<dt id="a91e894fe69f4a6c73074f7862ede5503">
const int <a href="#a91e894fe69f4a6c73074f7862ede5503" class="m-doc-self">Var</a> <span class="m-label m-flat m-primary">constexpr</span>
</dt>
<dd>A variable.</dd>
</dl>
</section>
<section id="a-group">
<h2><a href="#a-group">A group</a></h2>
<dl class="m-doc">
<dt id="a11d588fad4de0640556b055558c5fa1d">
<span class="m-doc-wrap-bumper">enum <a href="#a11d588fad4de0640556b055558c5fa1d" class="m-doc-self">Flag</a> { </span><span class="m-doc-wrap"> }</span>
</dt>
<dd>Flag in a group.</dd>
<dt id="ad769587e750dd7cd8de308987f7ccf30">
using <a href="#ad769587e750dd7cd8de308987f7ccf30" class="m-doc-self">Main</a> = void
</dt>
<dd>Alias in a group.</dd>
<dt id="ac65f93520b7abe37daa15a999faa4323">
void* <a href="#ac65f93520b7abe37daa15a999faa4323" class="m-doc-self">variable</a> <span class="m-label m-flat m-primary">constexpr</span>
</dt>
<dd>Variable in a group.</dd>
<dt id="abcad26bce92bd85654aaf9b7effc043b">
<span class="m-doc-wrap-bumper">void <a href="#abcad26bce92bd85654aaf9b7effc043b" class="m-doc-self">bar</a>(</span><span class="m-doc-wrap">)</span>
</dt>
<dd>Function in a group.</dd>
</dl>
</section>
</div>
</div>
</div>
</article></main>
</body>
</html>
49 changes: 49 additions & 0 deletions documentation/test_doxygen/compound_modules_in_namespace/file3_8h-stupid.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>file3.h file | My Project</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
<link rel="stylesheet" href="m-dark+documentation.compiled.css" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>
<body>
<header><nav id="navigation">
<div class="m-container">
<div class="m-row">
<a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
</div>
</div>
</nav></header>
<main><article>
<div class="m-container m-container-inflatable">
<div class="m-row">
<div class="m-col-l-10 m-push-l-1">
<h1>
file3.h <span class="m-thin">file</span>
</h1>
<p>Include file with some stuff that belongs to group 1 and group 2.</p>
<nav class="m-block m-default">
<h3>Contents</h3>
<ul>
<li>
Reference
<ul>
<li><a href="#namespaces">Namespaces</a></li>
</ul>
</li>
</ul>
</nav>
<section id="namespaces">
<h2><a href="#namespaces">Namespaces</a></h2>
<dl class="m-doc">
<dt>namespace <a href="namespaceNamespace.html" class="m-doc">Namespace</a></dt>
<dd>A namespace.</dd>
</dl>
</section>
</div>
</div>
</div>
</article></main>
</body>
</html>
32 changes: 32 additions & 0 deletions documentation/test_doxygen/compound_modules_in_namespace/namespaceNamespace-stupid.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Namespace namespace | My Project</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
<link rel="stylesheet" href="m-dark+documentation.compiled.css" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>
<body>
<header><nav id="navigation">
<div class="m-container">
<div class="m-row">
<a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
</div>
</div>
</nav></header>
<main><article>
<div class="m-container m-container-inflatable">
<div class="m-row">
<div class="m-col-l-10 m-push-l-1">
<h1>
Namespace <span class="m-thin">namespace</span>
</h1>
<p>A namespace.</p>
<p>This is a namespace. It is spread across two files.</p>
</div>
</div>
</div>
</article></main>
</body>
</html>
31 changes: 31 additions & 0 deletions ...ntation/test_doxygen/contents_anchor_in_both_group_and_namespace/namespaceFoo-stupid.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Foo namespace | My Project</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
<link rel="stylesheet" href="m-dark+documentation.compiled.css" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
</head>
<body>
<header><nav id="navigation">
<div class="m-container">
<div class="m-row">
<a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
</div>
</div>
</nav></header>
<main><article>
<div class="m-container m-container-inflatable">
<div class="m-row">
<div class="m-col-l-10 m-push-l-1">
<h1>
Foo <span class="m-thin">namespace</span>
</h1>
<p><a href="namespaceFoo.html" class="m-doc">Foo</a>.</p>
</div>
</div>
</div>
</article></main>
</body>
</html>
Loading

0 comments on commit 09ddeeb

Please sign in to comment.