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."

documentation/python: minor.

Those values are already available, so don't calculate them again.

doc: clarify the same for m.images default options.

doc: not everyone may like hyphenation or smart quotes.

Plus hyphenation requires extra packages, so don't suggest it by default
-- but clarify that those actually *are* the defaults and so the user
can omit them.

documentation/python: ensure all plugin hooks are always tested.

documentation/doxygen: recognize also <s> and <del> tags.

Followup to 12e0081a093ecf5e9dc287c549b4b521d45a2b6b.

documentation/doxygen: allow \xrefitem with numbers in the middle.

In Magnum I used to have \xrefitem aliases such as \requires_gles20 so
the current regex worked, but when adding \requires_gles20_only it
didn't work anymore. Such a stupid oversight, sorry to whoever else
tripped up on that as well.

Not updating any test case because regexes are write only anyway.

doc: mention m-clearfix also for floating elements.

That's where people will use it the most. Funnily enough the clearfix
already had to be used in the markup, so that's one more reason to
just put it directly in the snippet.

doc: clarify naming for such an important option.

Even I don't remember how it's meant to be named anymore, sigh.

package/ci: NOTHING IS EVER SIMPLE.

G'damit, can I just make the test run first *and only then* go on with
upgrading all the shit that broke in the few months while I was not
looking?!

package/ci: run tests verbose so it's clear what got skipped.

package/ci: install attrs as well.

Got a slight drop in coverage due to that.

m.dot: update graphviz 2.40 ground truth file.

I'll just assume it's correct.

package/ci: eugh everything is an unstable pool of mud.

package/ci: migrate to CircleCI.

Thanks, Travis, for being silent for three months straight. Fuck that
"service".

Add .yml files to .editorconfig.

m.htmlsanity: drop Flash-related code and fix compat with docutils 0.17.

That thing is DEAD so there's no reason to bother. This changed in
docutils 0.17, making the current version fail there. Funnily enough,
https://github.com/live-clones/docutils/commit/659c3f1e46f0c86609936c987b7e2a7a6ef89cb2
looks like they still seem to preserve that somehow. I won't, so all the
related code isn't needed.

The code here was originally taken from docutils but diverged
significantly and given that they still use the deprecated width/height
attribute I see no reason to even attempt cherry-picking their changes.

m.dot: support subgraphs.

documentation/doxygen: add a human-readable assert here.

Update CREDITS.rst.

Simplify formatting of ANSI-highlighted code

Omit superfluous g-AnsiDefault, g-AnsiBackgroundDefault classes

Add missing background styles

Correct comment regarding bright background colors

doc: update outdated Doxygen version requirement notices.

package/ci: go back to Pyphen 0.9.5.

As usual, every upgrade of every package breaks something.

Updated CREDITS.rst.

Update pagination Pelican template.

The template was hardcoded for the default reversed date ordering of
articles.

Fix doxygen base path resolution.

Use top-level doxygen path as base path. In case of recursive descent,
don't allow base path to be overriden.

doc: cross-link the Doxygen Show Undocumented option from more places.

doc: document what to do in Doxyfile for nice graphviz look.