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.

m.htmlsanity: fix an exception raised for .. contents:: with a title.

I have a hunch I was looking at this corner case, but of course forgot
to actually try it out. Extending the test to prevent this from
regressing again in the future.

documentation: doc++

documentation: properly calculate child offset for 11bit result counts.

Instead of fetching the exact same value twice and then forgetting to
patch it in one case, let's just reuse the patched value.

Hmmmm, this was a bug! And no tests caught it! Though, it was rather
unlikely to be hit in practice as the 100+th result would be cut away,
thus not even giving the user a hint to type futther.

documentation: trie pretty printing didn't handle the 11bit special case.

Better to have it tested directly, and not only through the JS
decoder part.

documentation: refresh search binary data layout docs a bit.

Updated CREDITS.rst.

css: consistently use pseudo-elements `::before` and `::after`

css, m.htmlsanity: use a <div> for .m-figure-description.

I can't read, apparently. Thought that the "flow content" on MDN doesn't
allow any block elements, only inline, but it does. So there's no need
to put a stupid <span> there and then try to make a block element out of
it via CSS again.

documentation: disable autocompletion with Android virtual keyboards.

Amazing, eh... wouldn't have thought that the virtual keyboard and the
mobile flavors of common browsers are SO CURSED that it's plain
impossible to achieve anything remotely usable in there. FFS.

documentation/python: improve pybind docstring parsing robustness.

It can't be ever made ideal since the output is not really meant to be
machine-readable, but expecting overload headers to be always at the
start of a new paragraph should hopefully rule out most accidental
matches.

documentation/python: try breaking the pybind11 docstring parser.

Yeah, not really great.

documentation/python: use full pybind11 docstrings.

documentation/python: add a test with full pybind11 docstrings.

Those get currently ignored.

m.htmlsanity: render TOC as a <nav> instead of <aside>.

documentation/python: use <nav> instead of <div> for the TOC.

documentation/doxygen: use <nav> instead of <div> for the TOC.

documentation/python: ignore enum values when checking for duplicates.

The test now passes again.

documentation/python: test checking for duplicates with enums present.

This asserts because the enum entries don't have the .object property.
Fix in the next commit.

documentation: minor cleanup.

documentation/doxygen: test that direct HTML embedding works.

It should since 1.8.18.

m.htmlsanity: work around FF misbehavior in <figure> printing.

Counterpart to the previous commit. Done only if the figure has a
.m-figure CSS class, as that's where the Firefox bug is triggered due to
the `display: table-caption` -- code figures and console figures are
unaffected.

There's still a bit of potential future work where the figure
description shouldn't have any block-level elements. But that doesn't
trigger any rendering bugs so not so important.

css: work around Firefox-specific behavior with .m-figure.

The `.m-figure > *` has `display: table-caption;` to make overlong
content wrap to width of the image, instead of pushing out the figure
border. However, this makes Firefox render just the first element and
ignore everything after, thus the original figure descriptions weren't
visible in Firefox, only in Chrome.

Because HTML5 says <figcaption> has to be right inside <figure>, I can't
wrap the caption together with other content in a <span>, although that
would make Firefox render things properly. Instead I'm nesting all
description inside <figcaption> in a .m-figure-description, which then
reverts all styling applied for <figcaption>. Kinda ew, but works.

Originally this was reported for just image figures, but the same
problem applies to math and graph figures as well. Not for code/console
figure though, as those don't have `display: table-caption;` and instead
span the whole width always.

This has to be fixed in m.htmlsanity as well, doing that in a separate
commit as it's a bit involved as well.

Drop support for Graphviz < 2.40.

Mostly an inheritance of the old Travis CI images. CircleCI has Graphviz
2.42.2 which has the output consistent with 2.44, and Ubuntu 18.04 has
Graphviz 2.40.1, so that's the oldest reasonable minimum to care about.

m.htmlsanity: don't rely on .m-transition, again.

Followup to 3f7b8501c98bfead4047f397a527e096ac75e26a. Was fixed in one
place but not in the other. Also add a clarifying comment.

documentation/python: drop pybind11 2.2 support.

Version 2.3 is the oldest supported now. It got released in Oct 2019 and
there were a bunch of extra hacks needed for 2.2. Ubuntu 18.04 has 2.0.1
which isn't feasible to be supported either, but 20.04 already has 2.4,
so staying at 2.3 at a minimum is good enough I'd say.

m.htmlsanity: adapt to changes in docutils 0.18+.

And explicitly test for 0.14, 0,17.1 and 0.18.0 on the CI.

Updated CREDITS.md.

m.htmlsanity: change transitions into Docutils transition nodes.

m.htmlsanity, m.components: expand transition tests.

The m.css .. transition:: directive should behave the same as builtin
transitions, but it doesn't. Fix in the next commit.

documentation: this import isn't needed.

documentation/*: add a SEARCH_FILENAME_PREFIX option.

Allows to override the search data filename, which is useful when both
Python and C++ documentation shares the same directory. Otherwise both
would use the same search data filename and overwrite each other's data.

m.plots: update to work with matplotlib 3.5 as well.

The major change in 3.5 is that the attributes have a different order
and styles have more whitespace and less semicolons. To avoid explosion
of find/replace patterns, the search strings were converted to regexps
-- which on the other hand allowed me to drop some duplicates, and
discard the font name replacement altogether.

On the CI I'm now using the latest version on Python 3.8+, 3.7 stays on
3.4 to avoid regressions on that versions, and 3.6 on 3.3 which is also
a bit different.

documentation/python: don't try to parse pybind objects as enums.

Followup to c6707e1c85a46e8848ebca077ec60eeb27eb5aab, forgot to test on
a real-world codebase early enough. And then of course forgot to handle
a corner case when accounting for that real-world scenario.

package/ci: doc++

package/ci: test for Pelican 4.2 on the Py3.6 image.

documentation/python: adapt for attrs 20.1+.

Also starting to use the 3.6 CI job to test hacks for older packages.

m.plots: adapt to changes in matplotlib 3.4.

Version 3.5 is a whole other beast (different order of XML attributes
altogether), will need to be handled in a separate step.

package/ci: now that attrs are needed always, handle them in one place.

It was done this way because Python doc generator wasn't working on
Python 3.5. But 3.5 is no longer tested for.

Fix minor typo in doxygen.rst

m.htmlsanity: update tests for Pyphen 0.10+.

I like the output less, but what can I do. Not in my power to change.
The only relevant difference in the changelog from Pyphen 0.9.5 to 0.10
is a dictionary update, so I guess that's what did it. Shrug.

m.images: properly close images opened with PIL.

Python 3.10 yells at me if I don't. Useful warning. (Ahah, C++ and your
sane scoping rules, I miss you.)

m.qr: update test files for qrcode >= 7.1.

It changed from an inline style to separate attributes. Luckily all
platforms I test on have pip with 7.1 available, so I don't need to
branch out even further with the test files.

documentation/python: support insane pybind 2.6 enum printing.

What the hell, why.

documentation/python: improve error reporting in pybind signature parser.

The exceptions were mostly there, but the text got lost at the end!
Silly.

documentation/python: expand pybind default enum argument tests.

To verify also a case with an enum nested in a pair (which won't get
linked to because we're not *that* advanced yet).

documentation/python: typing.Generic.__new__() is gone in 3.9.

documentation/python: implicit TypeVar for typing.List was only in 3.7/8.

If I say typing.List, only Python 3.7 and 3.8 converted that to
typing.List[T], 3.6, 3.9 and 3.10 keep typing.List.

m.qr: actually, the difference is *also* due to Python versions.

Somehow the attributes have different order, generating a MONSTROUS
difference.

Heh! Why! Why do I have to suffer this much all the time.

package/ci: haaaaaaaaaaaahhhh docutils also.

Just half a day and I already miss the stability of C++ development.
FFS.

m.dot, documentation/*: use graphviz 2.44 output for 2.42.2 also.

Hope this finally makes the CI pass.

package/ci: use older Pygments until I update the test files.

package/ci: use older qrcode package until I update the regexes.

package/ci: drop Python 3.5 testing, add 3.8 to 3.10.

Python 3.5 was EOL'd in September 2020 and support for it is being
removed from major packages like pybind. It was also the only version
on which neither the Doxygen nor Python doc generator worked due to lack
of typing annotations, and since those two are the major use cases, I
don't think there's many users relying still on 3.5.

Python 3.6 was EOL'd in December 2021 so *technically* I could drop it
as well, however Ubuntu 18.04 LTS still has it as the default version so
it's good to keep it. I don't really need to use any 3.7-specific
features yet either, so this isn't a problem.

pelican-theme, m.code, m.dot: make stuff finally work on Pelican 4.5.1+.

Since Pelican 4.5 moved to "namespace plugins", the way plugins are
loaded is different and thus the root plugins/ directory is not in PATH
anymore, leading to errors like

    No module named 'ansilexer'
    No module named 'latex2svg'

After spending a bit of time looking into how "namespace plugins" are, I
decided to stay with what they say "legacy plugins" because that doesn't
require me to move everything into a pelican.plugins namespace and thus
allows me to reuse the exact same file for plugins to other m.css tools
like the Python doc generator.

Version 4.5.0 had loading of namespaced plugins (the `m.` here) broken
completely, which is why the CI got pinned to 4.2. With 4.5.1 it started
working again and due to how the tests were executed the PATH issues
weren't hit either, leading me to a false sense of security that
everything works again on 4.5.1, while it wasn't. This fix is the final
piece to make everything work again. Sorry that it took over a year to
get in.

Co-authored-by: Lukas Pirl <git@lukas-pirl.de>

m.plots: fix a deprecation warning with matplotlib 3.5.

It complains that "Support for setting an rcParam that expects a str
value to a non-str value is deprecated since 3.5 and support will be
removed two minor releases later."