documentation/doxygen: avoid another version-specific parsing behavior.

While the empty paragraph made 1.8.16 turn the second item into a
paragraph as well, 1.12 now treats that as the end of the list. Use
another sentence instead, which behaves the same on both.

documentation/doxygen: don't rely on a Markdown parsing bug in a test.

This was deemed to be an error in
https://github.com/doxygen/doxygen/commit/5f75ff14582400a77068df5ff0f4f0ec0693adee
and 1.9.3+ doesn't behave like that anymore.

documentation/doxygen: anonymous namespaces no longer garbage in 1.9.7+.

They no longer have <compoundname> containing some randomly generated
string containing @, but it's empty instead. Similar as with enums that
were adapted to in c0194a3eb81057a3b029e66cf389a35f64375eef.

documentation/doxygen: some Markdown autobrief insanities gone in 1.12.

documentation/doxygen: noexcept and constexpr no longer leaks into types.

Since Doxygen 1.11. Which means I now have to use the attributes. No
change to the test files is needed, without this change 1.11+ would
produce output that doesn't have noexcept and constexpr.

documentation/doxygen: Doxygen 1.12 can produce up to <sect6>.

And is slightly less broken when encountering Markdown headers where
it's not #'s at the start of the line but underneath.

documentation/doxygen: normalize hashes before comparing files.

Each Doxygen version differs slightly in those and I just have no
patience for it. The actual on-disk files keep the originals so anchors
and everything works, but they're replaced when comparing.

documentation/doxygen: properly adapt all tests to graphviz 10.

Forgot this in 182939f4d403c42c061b6d37907fab2286b6da24.

documentation/doxygen: remove static keyword from variable types as well.

Like was done in a74bdefc58a34b8054e61e84b480ad6cf0105ad2 for functions.
I didn't notice until now, but Doxygen 1.11 finally fixed that, which
uncovered the mistake in the test_compound.Listing test.

documentation/doxygen: normalize spacing around inline <mcss:*> tags.

Those are \xmlonly, and Doxygen 1.12 (or anything between 1.12 and
1.8.16) seems to put one more space there, causing useless differences
in test files. Replacing those with just one space to have a consistent
output across all versions.

test: fix Python 3.12 warnings about invalid escape sequences.

Or maybe 3.11 warned too and I just didn't notice?

documentation/python: adapt to changes in Python 3.12 builtins docs.

documentation/doxygen: whoops, bad test filename.

Broken since 182939f4d403c42c061b6d37907fab2286b6da24.

documentation/doxygen: fix hopefully all ElementTree deprecation warnings.

No, it didn't get any better with this change. Only more brittle.

documentation/doxygen: fix anonymous enum parsing with 1.9.7+.

documentation/doxygen: expand the enum test with anonymous enums.

This was verified only in an "integration" test along with a ton of other
features, better to have a dedicated case for it as well.

docummentation/python: adapt __weakref__ ignore to Python 3.11.

package/ci: pin to numpy and pybind11 that work together.

Without breaking my tests. Gah, I hate this pointless churn.

doc: adapt Build Status to codecov API changes.

doc: updated credits.

m.htmlsanity: traverse() is deprecated since docutils 0.18.

Looks like it got changed to an iterator to be faster, unfortunately
Sphinx relied on it returning a list, so it got changed back and
deprecated in favor of findall().

Using the new name and adding it as an alias for traverse() on older
versions.

m.code: reprunicode() is also gone in docutils 0.21.

Their changelog says it was there just for compatibility with Python 2,
which m.css never supported anyway.

Co-authored-by: John Turner <7strbass@gmail.com>

m.code: stop using stuff removed in docutils 0.21.

The uses were just copypaste from the upstream implementation, and out
of all imports only the error string was used. The documentation
suggests using just str() instead, which is what I do, even though it's
different from what ErrorString actually formatted.

m.dot: adapt test to differences in output with graphviz 10.

Or 9, or maybe 8 or 7. The version I tested with before was 2.44, no
idea why was it so important to suddenly change the versioning scheme
like this.

m.plots: adapt tests to different output with matplotlib 3.6+.

Unfortunately version 3.8+ has different output YET AGAIN, meaning I
have to pin again until I build up the patience to retry all this.

m.qr: adapt to different output in qrcode 7.4.

Stop using deprecated distutils.version.LooseVersion in tests.

I was waiting *half a decade* for this to get resolved in a less than
insane way, but NOPE. Instead of using builtin functionality for such a
basic operation as version comparison (heck, even CMake has that
builtin!!) we're now instructed to PIP INSTALL PACKAGING. Where did the
"batteries included" spirit go? Why is everything increasingly
overengineered? Why can't a project stay in place for a few years, WHY
DO I HAVE TO ADAPT TO MEANINGLESS CHANGES ALL THE TIME?!

latex2svg: restrict the libgs workaround to dvisvgm < 3.0.

On newer versions this isn't needed, and the hardcoded paths aren't
always enough. So better to just not try at all.

css: support .m-image and .m-figure for <video> as well.

latex2svg: look for libgs.so.10 in /usr/lib64 as well.

Update copyright year.

Six months in, I could have waited until 2024, heh.

Stop mentioning Pelican -- it's a general site theme independent of it.

doc: properly show that a class directive *is* needed for a table.

The output markup had it but the snippet not, causing confusion.

m.code: make it work with newer docutils.

Not sure when this got broken but omitting the option no longer works.

documentation/python: test external doc overload matching with * and /.

With the previous commit this now "just works", as the placeholders are
dropped from the final signature. The test thus works mainly for
documenting this feature.

documentation/python: recognize / and * in pybind11 signatures.

documentation/python: ignore a new useless builtin on 3.11.

documentation/python: don't use deprecated distutils.

Turns out the version info can be compared much more easily. Thanks
Python, this is nice.

latex2svg: work around dvisvgm < 3.0 not detecting ghostscript 10.

The latex stack and everything around it is ... interesting. A huge pile
of stuff that randomly breaks in very silent and non-obvious ways, and
it's all so huge and complicated that even distro package maintainers
have no way to know if the packages are mutually compatible.

Now that I figured this out, I still need to comment on that ArchLinux
bug.

latex2svg: more robust handling of libgs not being found.

Instead of just looking it up upfront and then hoping for the best,
verify also that dvisvgm actually detected and used it. Because it not
always does, in particular with versions < 3.0 and ghostscript 10.

m.code: minor.

css: reduce size of the jumbo header.

The previous size was unbearable with longer titles such as in
https://blog.magnum.graphics/backstage/cpu-feature-detection-dispatch/

doc: update command line for Pygments CSS generation.

m.code: support inverse video in the ANSI lexer.

I'm very glad for the extremely extensive code coverage here. Without
it, I'd break half of other stuff by accident.

m.code,doxygen: test inline ANSI code highlighting.

Because it got broken with Pygments newer than the ancient 2.6.1 fork I
have (it now unconditionally adds a wrapper <div>), and unfortunately I
can't see how to not do that in 2.14 without delegating into private
APIs.

So just to have that problematic part reproduced in tests, once I get to
that. Unfortunately latest Pelican doesn't work with older Pygments
anymore for some reason (or, well, disallows it), so I can't generate
the website until I have this fixed properly. Ugh.

package/ci: the eternal trash fire of random packages breaking!!

I have no patience for any of this.

documentation/python: test using :property: in a class docstring.

It works, I just wasn't sure if there wasn't something special regarding
docstrings so I had to check explicitly.

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.

css: document that a <table> can be .m-fullwidth.

I kinda forgot all the particulars since I made this five years ago, so
better document everything for my old soul.

package/ci: I HATE WEB DEVELOPMENT

All packages getting changed all the time with stupid differences. IT IS
NOT POSSIBLE TO JUST HAVE A PROJECT WORKING FOR SIX MONTHS WITHOUT A
CONSTANT NEED FOR ADAPTING TO CHANGES IN DEPENDECIES FFS!!!

I miss developing against Qt, where the APIs I used in 2007 were still
there in 2014. ARGH

Updated CREDITS.md.

fix typos in m-components.css

m.code: fix ANSI lexer compatibility with Pygments 2.12+.

I'm still pinned on an older version because of the significant
difference in output, but it shoulnd't crash at least.

m.dox: document a rather nasty abuse of lack of python variable scoping.

m.dox: restore compatibility with cppreference tag files.

These put the filename into a different tag, and don't use anchors.

m.dox: test & fix linking to files, defines and macros.

The tagfile has an absolute path for some reason, but not going to
bother with that right now. The code was also appending one extra .html
extension, which is fixed.

m.dox: allow linking to variables as well.

I have *many* tags now, and need to be able to refer to them.

m.dox: properly test also links to typedefs, enums and enum values.

Instea of updating the Corrade tagfile, which would be several megabytes
of useless data, I'm now cherry-picking just what's changed.

Will make updates slightly harder but not impossible (can't just replace
the whole file but have to cherry-pick again). OTOH I can now use the
same approach for STL-tagfile-specific workarounds instead of bundling
another 2 MB of XML data.

Use two-space indentation for Doxygen tagfiles.

Updated CREDITS.rst.

documentation/doxygen: explanatory comments for parts without CI coverage.

Also restoring the note about the cpp_function_attributes regression
test.

doxygen: fix keywords leaking into return type

- fixes #225
- fixes #226

Also drive-by added support for C++20's `consteval` keyword.

Fix documentation typos

Updated CREDITS.rst.

documentation: Use https links instead of git links.

GitHub no longer supports git:// links. Trying to
following the clone instructions leads to an error:
>  The unauthenticated git protocol on port 9418 is no longer supported.
> Please see https://github.blog/2021-09-01-improving-git-protocol-security-github/ for more information.

documentation/doxygen: don't omit functions w/o brief from file docs.

Before, functions that contained for example /** \overload */ were
omitted from file docs, leading to user confusion.

And document the behavior more thoroughly -- took me a while to realize
this condition was really responsible for this.

documentation: it's Doxyfile.xml I shall ignore, not Doxyfile.html.

Made an error in 45911a18 and apparently it was fine because it silently
returned in some later check.

Jabber? What's that?

Updated CREDITS.rst.

Fix various typos

Found via `codespell -q 3 -L nd,te`

Co-authored-by: Vladimír Vondruš <mosra@centrum.cz>

documentation/doxygen: don't trip up on WEIRD macros parsed as functions.

documentation/doxygen: the xrefim order change was just "temporary".

Followup to 4ec09a2c97f60c2c673de337d7dabdc198592f4a. A temporary
regression from 1.8.18 to 1.8.20, 1.9.0 is back to what 1.8.17 had. Heh.
Heh.

documentation/doxygen: silly block-separating workaround for Doxygen 1.9.

Now the new test_contents.Blockquote test passes fully.

documentation/doxygen: drop STUPID &zwj; in <blockquote>.

What the hell, such a pile of unnecessary work. FFS.

documentation/doxygen: fix Doxygen 1.9 code-after-blockquote bugs.

Before it was wrapped in a dedicated paragraph, now it's not anymore.
Thus, if a <programlisting> is right after a <blockquote> and there's
nothing else after it until the end of <para>, it should be treated as a
code block again.

documentation/doxygen: dedicated test for Doxygen 1.9 blockquote bugs.

And removing the problematic interaction from the general typography
test -- it's now here instead.

documentation/doxygen: adapt to different \dotfile handling in 1.9.3.

documentation/doxygen: don't add a space between <p> and <code>.

Seems obvious in retrospect, but for some reason I never realized.

documentation/doxygen: fix another void \return docs warning with 1.9.

Followup to 568edda0b4c2f4ff53652a28aa27a89cb54c2aac.

Updated CREDITS.md.

latex2svgextra: adapt to minor changes in dvisvgm 2.12 preamble.

And add an actually useful assert message.

Co-authored-by: Vladimír Vondruš <mosra@centrum.cz>

documentation/doxygen: add a clarifying note to the test Doxyfile.

documentation/doxygen: repro case & fix for a blockquote in brief.

Amazing. Such a *tiny* piece of functionality with a clear goal,
providing a single-line brief with no block elements. And yet this is
like the 50th bug I came across, so far.

Revert "documentation/doxygen: drop handling for a Doxygen 1.8.15 bug."

Turns out it's not really A Thing Of The Past yet -- the assertion is
firing for different cases and the message of it is utterly confusing.
Repro case for the others in the following commit.

This reverts commit 6bea7027cb2674e4c5f78a527ddab506d9785675.

documentation/doxygen: fix a friend class being parsed as a function.

Doxygen 1.9 no longer contains a "friend" prefix in the <type>, causing
some conditions to trip up and some asserts to trip up even worse after
that.

Co-authored-by: Vladimír Vondruš <mosra@centrum.cz>

documentation/doxygen: silence a warning.

Hopefully this wasn't omitted there for some testing purpose.

documentation/doxygen: ah so that's why the warning is uncovered.

Because 1.8.16+ just directly drops the whole <dotfile> tag if the
source doesn't exist. What a marvellous idea!!!

documentation/doxygen: fix Doxygen warning.

Funnily enough this doesn't make the multiline brief bug go away. So
what's even the point of checking those, Doxygen?!

documentation/doxygen: explicitly check for warning logs.

The output was quite a mess already, and that's just because I didn't
know about assertLogs() until now.

documentation/doxygen: Doxygen 1.9.3 warns about \return for void.

And quite intensely. Don't do that, then.

documentation/doxygen: since 1.9.2, HAVE_DOT has to be explicitly set.

Kinda silly to require that even for the XML output, where Graphviz
doesn't actually need to be used at all -- the content/files are pasted
verbatim.

documentation/doxygen: robustly skip unexpected XML files.

This skips the Doxyfile.xml from 1.8.19 (without a warning, to avoid
polluting the output for everyone running newer Doxygen), and
additionally also all other files that don't have the expected root or
immediately following tags (with a warning, because that's likely
something to act on).

These checks used to be inconsistent between extract_metadata() and
parse_xml() (resulting extract_metadata() to continuing further and
dying on some other exception, sigh) and also was an assert instead of a
graceful handling.

A new test case is added to verify that all expected messages are
printed, all unexpected files are skipped but also the expected files
are not skipped. The warnings/errors are also printed just once, not
once during metadata extraction and once during actual page generation.

Co-authored-by: crf8472 <crf8472@web.de>
Co-authored-by: SRGDamia1 <sdamiano@stroudcenter.org>

documentation/doxygen: adapt test output for silly 1.8.18 differences.

Is this a random order? FFS.

documentation/doxygen: all strikethroughs are supported only in 1.8.17.

documentation/doxygen: don't set a config value twice in the test.

documentation/doxygen: 1.8.16 doesn't support subpages of index.

These just aren't marked as such. So skip the direct test and rewrite
the other to not accidentally use this functionality.

package/ci: test against Doxygen 1.8.16 and 1.8.18 as well.

Preparing for the final boss which is 1.9, but!

 * 1.8.13 downloads and runs fine, but there's way too many test
   failures and I'm not ready for these. Probably will just drop the
   support eventually.
 * 1.8.14 to 1.8.15 links to libclang.so.6, which is not a thing on
   Ubuntu 18.14. I suppose this is because SOMEBODY built the damn
   release binary on their own PC, instead of in an old enough sandboxed
   environment, HA?!
 * 1.8.16 and 1.8.17 work, just a bunch of fixes needed to make test
   pass on .16.
 * 1.8.18 works, except it relies on some silly libtinfo.so.5 that I had
   to install.

Update copyright year.

Pro Tip: if you update only once every two years, you save 50% of the
work! 50%!!!!

documentation: expose search data packing options.

There are new SEARCH_RESULT_ID_BYTES, SEARCH_FILE_OFFSET_BYTES and
SEARCH_NAME_SIZE_BYTES options exposed in both Doxygen and Python doc
generator. Because they affect some internals that the regular user
shouldn't need to care about and don't reflect anything tangible like
project symbol count, they're not really documented.

On the other hand, they can't really be estimated beforehand The
estimator would either overestimate, leading to files larger than they
could be, or it underestimates, leading to random corner cases that
would be impossible to track down. Thus the project just starts with the
small sizes and if they're not enough, an exception with a (hopefully
helpful-enough) message is raised, suggesting users to adjust their
config.

documentation: parametrize the search binary data type sizes.

Needed in order to support more than 65k symbols or files larger than 16
MB. What I thought was "more than enough" during the initial design was
quickly stepped over by various projects, including my own Magnum Python
bindings.

To avoid having to either maintain two separate formats and two separate
en/decoders or needlessly inflate the format for everyone, certain data
types are parametrized based on how large the data is:

 * RESULT_ID_BYTES describes how many bytes is needed to store result
   IDs. By default it's 2 (so 65536 results) but can be also 3 (16M
   results) or 4.
 * FILE_OFFSET_BYTES describes how many bytes is needed to store file
   offsets. By default it's 3 (so 16 MB), but can be also 4.
 * NAME_SIZE_BYTES describes how many bytes is needed to store various
   name lengths (prefix, suffix lengths etc). By default it's 1 (so 256
   bytes at most), but can be also 2.

At first I tried to preserve 32-bit alignment as much as possible, but
eventually realized this is completely unimportant in the browser
environment -- there's other much worse performance pitfalls than
reading an unaligned value. This is also why there are 24-bit integer
types, even though they're quite annoying to pack from Python.

Furthermore, the original hack to reserve 11 bits for result count at
the cost of having only 4 bits for child count was changed to instead
expand the result count to a 15-bit value if there's > 127 results. Some
endianness tricks involved, but much cleaner than before. I briefly
considered having a global RESULT_COUNT_BYTES parameter as well, but
considering >90% of result counts fit into 8 bits and this is only for
weird outliers like Python __init__(), it would be a giant waste of
precious bytes.

The minor differences in the test file sizes are due to:

 * The header expanding symbol count from 16 to 32 bits (+2B)
 * The header containing type description and associated padding (+4B)
 * The result map no longer packing flags and offsets together, thus
   saving one byte from flags (-1B)

To ensure there's no hardcoded type size assumptions anymore, the tests
now go through all type size combinations.