documentation/python: expand annotation tests with string fallbacks.

In both cases the actual annotation is left as a string. Those were so
far tested only as part of inspect_type_links, but the behavior isn't
limited to linking.

documentation/python: properly handle nested INPUT_MODULES.

The use case is explicitly including a module that otherwise doesn't get
transitively imported from the parents. They were treated as a standalone
root module until now, causing quite a mess. Now they aren't, but there's
an additional check requiring the user to explicitly supply also all
parents.

documentation/python: the plain type name wasn't correctly name-mapped.

Fortunately the template uses the type_link property, so this bug wasn't
really visible anywhere.

documentation/python: no reason to have the same code in two branches.

Also it could be a plain join(), without having to parse the format
template.

documentation/python: show function values as ellipses as well, for now.

Putting `<function whatever>` into a Python stub file isn't a good idea
at all, as it's a syntax error. It isn't really useful for the HTML
output either because there's just the name, not the fully qualified
function, and it's not a link either.

I may eventually go back to this and make those actual names and links
if the functions are known, but right now there are other, more important
things left to do.

documentation/python: use an actual ellipsis literal for invalid values.

When they're either too long or unrepresentable, so it can be used also
in actual Python (stub) code, the single-character Unicode thingy cannot.

documentation/python: fix mismatched external docs in inspect_attrs test.

documentation/python: when signature fails, leave it up to the template.

Passing an ellipsis to the template made sense when there was just a HTML
output, but for generated stubs that's not a valid syntax. So output a
single parameter with name being None instead, and let the template
decide what to do there.

In case of pybind, the code was inconsistently using the Unicode
ellipsis. Now it returns None too, and thus the template handles both the
same.

documentation/python: explicitly test builtin BaseException as well.

It contains members with unresolvable signatures. It's now tested through
a derived class in test_inspect.String, but once base class members get
omitted from the output, that gets lost.

documentation/python: test annotation special cases in a less hacky way.

We can just pull those into a custom module with __all__, no need to
modify directly math.__all__. This also means we don't need to worry
about the module-level docstring.

documentation: tighten up writing of trailing newlines.

documentation: don't exclude trailing file whitespace in tests.

This makes it impossible to ensure that a template doesn't leave extra
newlines at the end.

documentation/python: further expand the list of ignored dunder names.

documentation/python: defer HTML escaping until the template is rendered.

Except for stuff that may itself contain actual HTML, such as type /
value links or the summary / details prose rendered from reST. Needed to
be done this way in order to be able to generate Python stubs without
having to nastily unescape for them again.

documentation/python: expose pybind enum value values as str, not int.

The template apparently doesn't care, but calling html.escape() on that
thing is an error.

plugins: add a test for parse_version().

Forgot to add this file in 8f080819783f2daf085d8b8d954dcbee4d27c2a9.

documentation/python: expose also plain relative types to the template.

Not just type links, but also plain types with redundant name prefixes
removed, for use in contexts where a link doesn't make sense, such as
tooltips. They're HTML escaped like the other variants, but right now not
used in the template at all.

The only breaking change is that what was `param.default` / `data.value`
is now in `param.default_link` / `data.value_link`. Those are different
from `param.default` / `data.value` only if the type is a (known) enum,
in which case the link is to the enum value, other than that these two
are the same.

documentation/python: this variable is set in both branches below.

No need to have it set before at all, this makes it more error-prone.

documentation/python: fill property.type_link and param.default always.

Also not sure what that commented-out return was about.

documentation/python: explicitly pass the output directory to render().

There will be another output directory for the stubs. Also prefer to use
local variables over properties, it's (hopefully) less string lookups
that way.

documentation/python: and yes, these two branches were impossible to hit.

Wouldn't have discovered that without the parent commit.

documentation/python: put content of branches on a next line.

This makes it way too easy for given code to be accidentally not covered.

documentation: verify HTML escaping for both the doxygen and python theme.

It's a mess and needs to be cleaned up, especially given that I now need
to have non-HTML output from the Python generator, so it's good to have
it actually regression checked.

This actually revealed one superfluous unescape in the Python theme
(which was likely a leftover from when that code was copypasted from the
Doxygen theme), and a Doxygen bug where it doesn't unescape image alt
text. Then m.css doesn't correctly escape the alt text either, which
makes the bug cancel out and everything is alright.

Oh and there's also a bug where if special HTML chars are used in
filenames, it breaks the Doxygen XML output. I should probably make a PR
for those two.

documentation/doxygen: this warning isn't related to any file.

It may get printed when preprocessing the state from all files (building
parent/child hierarchies, etc), listing a random file for that is
extremely confusing.

Well, the whole message is extremely confusing, so let's redo it,
suggest a fix and also have a test for it, instead of excluding it from
coverage.

documentation: ignore the test directory for code coverage.

documentation/doxygen: ignore branch that we have no chance of reaching.

documentation/doxygen: properly cover stripping links from code blocks.

This got broken when I was stripping down the tag file. Adding comments
in a hope that it won't break again.

documentation/doxygen: properly handle <sect5> and <sect6> everywhere.

Insufficient testing in 2b57d535dfddbee13cb30ad352c42e68e7915553 and
before led to this (hitting the unreachable assert below), fortunately
looking at code coverage revealed the "more than three levels of
Markdown headings" message was never tested properly.

documentation/python: adopt PEP585 naming for pybind11 typing hints.

This is what pybind11 2.12+ does, but as I have to parse the docstrings
and prepend the `typing.` namespace, I can retrospectively make this
change for older pybind11 versions as well. In particular, the following
is changed in type annotations of generated documentation, independently
of pybind11 version:

 - typing.Tuple is now tuple
 - typing.List is now list
 - typing.Dict is now dict
 - typing.Set is now set

If the python standard library inventory file is used, the type
annotations in signatures will now link to the builtin types instead of
the typing module.

Note that if your documentation uses external docstrings and matches
overloads by the signature, you may need to adapt the rename to make
them match again.

m.code: adapt to pygments 2.10 to 2.18.

The new versions properly qualify whitespace as such instead of as text,
and do so gradually, which is responsible for most changes in the
output. Besides that, until 2.14 there were certain cases of empty
<span> in the output, which 2.14 fixes, so I add a postprocessing step
to clean those up to not need to further branch the tests.

The CI now tests various pygments versions, with only the last job
taking the latest version.

m.code: fix AnsiLexer to actually do the right thing with pygments 2.12+.

That extra removed argument did make it "work", but due to the internals
being different, all ANSI output was additionally wrapped in
<div class="highlight">. Now it's not anymore.

m.code: split away ANSI highlighting to a separate test file.

The output of AnsiLexer doesn't change depending on Pygments version,
which means I don't need several copies of it, unlike the rest.

doc: fix broken links and links that aren't links at all.

m.math: properly include the m.components plugin in all tests.

So when just one is run, it doesn't fail on something silly like the
.. math-figure:: directive not existing.

m.math: minor cleanup.

m.math: render M_MATH_RENDER_AS_CODE with .m-code.m-math classes.

As well as any other that were specified, so even the fallback can
retain coloring and such.

m.code: allow inline code and code blocks without any language.

Inline code supported that already, but omitted the .m-code CSS class in
that case, and also all other classes. Code block didn't support that.
Now both do, and both preserve both the .m-code CSS as well as any
custom ones.

m.math: expand the visual test with inline math.

The CSS classes and DOM nodes are placed different but it should look
exactly the same.

css: fix more Python 3.12 unknown escape warnings.

documentation/doxygen: support the M_MATH_RENDER_AS_CODE option.

Updated credits.

documentation/doxygen: don't use <includes> w/o STRIP_FROM_PATH defined.

The damn thing then just strips all directories and keeps just the leaf
name, which is completely useless. One would think setting
STRIP_FROM_INC_PATH to `.` is the same as leaving it empty, but
apparently not!

documentation/doxygen: cleanup, test, support overriding the file too.

Not just the header name, but also where the link points to. None of
this is possible for namespaces, functions or other symbols, which is a
bit sad, but that's Doxygen we're dealing with here.

documentation/doxygen: support for STRIP_FROM{,_INC}_PATH.

Doxygen support for STRIP_FROM_INC_PATH is applied to class/struct and
enums through the <includes> xml tag. m.css additionaly shows such
information for functions, enum, namespaces, typedef, variables and
defines through the information extracted from the <location file="xx"/>
tag.

However the location available through the <location file="xx"/> is not
stripped using STRIP_FROM_INC_PATH, only STRIP_FROM_PATH.

This patch provides STRIP_FROM_INC_PATH support by building the prefixes
(STRIP_FROM_INC_PATH stripped from STRIP_FROM_PATH) and stripping the
longest match when constructing the include html.

Co-authored-by: Yuri Edward <nicolas1.fraysse@epitech.eu>
Co-authored-by: Vladimír Vondruš <mosra@centrum.cz>

documentation/doxygen: add support for class-specific location.

When documenting a class, a struct or an union, Doxygen allows the user
to specify a custom header.

Doxygen doc:
  \class <name> [<header-file>] [<header-name>]
  \struct <name> [<header-file>] [<header-name>]
  \union <name> [<header-file>] [<header-name>]

The specified <header-name> can be retrieved between the
<includes></includes> tag of the generated xml for the
classes/structs/unions constructs.

This patch uses <header-name> instead of the default path extracted from
the <location file="xx"/> without modifying the location.

This also fixes #137 for these three constructs when the user does not
define the <header-file>/<header-name>, because the value present inside
the <includes> tag is stripped using the Doxygen STRIP_FROM_INC_PATH
option, whereas <location file="xx"/> is not. Hence, there is still an
issue for namespaces, free functions, enums, typedefs, variables and
defines which are not part of a class/struct or union.

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

doc: show pybind11 and doxygen versions in the build status page.

Update credits in all files.

Compared to other projects, where I make sure to do this, I was quite
winging it here, heh.

documentation/doxygen: support img alt properties.

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

documentation/doxygen: ignore unsupported languages instead of blowing up.

Should have done this from the beginning instead of repeatedly telling
people that the cannot include JS or python files as part of the doc
build.

Interestingly enough, file.js gets still treated as C++. Had to switch to
Java to make it detect as something that's not C++.

It's high time I updated the copyright year.

pelican-theme: don't attempt to query a Pelican version in the test.

Because I rely on ancient pygments (gotta fix that too), I cannot use
Pelican 4.9.0+ as it requires a newer version. And on Python 3.12
pelican.__version__ with Pelican 4.8.0 says "unknown" (probably due to
not being ported to the new packaging thingy or whatever), breaking the
version parser in the test.

I'm querying the version just to skip a test that relies on a PR that I
opened in 2017 and didn't have time to get back to. I likely won't have
for another decade, so can just skip this always.

package/ci: test on Python 3.11 and 3.12, and Doxygen 1.9 and 1.11 also.

1.12 has extremely broken typedef merging which is making too many tests
failing, so can't test on that one, or at least until my PR is merged.

documentation/python: fix annotation extracting for typing.Any on 3.11+.

documentation/python. adapt inspect tests to Python 3.11 / 3.12 changes.

documentation/python: adapt builtin method filters to changes in 3.11+.

documentation/python: match the filtered builtin functions to the source.

So when a new Python version changes the docstring, it can be easily
found.

documentation/python: don't use test skipping for version branching.

So much duplication, ew.

documentation/python: enum.IntFlag in newer Python doesn't like NPOT.

The FLAG_SEVENTEEN _is_ there if I explicitly call it, but it doesn't
show up in autocompletion or help. Turning it into a power-of-two value
makes it appear.

Heh. Heh.

documentation/doxygen: properly escape HTML <>s in a test.

This was making Doxygen 1.10 + 1.11 fail parsing the link title,
substituting for an empty text. Funnily enough 1.12 doesn't suffer from
that anymore, which is what made me think that was a Doxygen bug and not
mine. Well it still *is* a Doxygen bug, but at least now I can have
consistent output everywhere.

documentation/doxygen: adapt test to spacing changes in math in 1.9.x.

Not sure which version, really. Don't want to plow through the
messy changelogs.

documentation/doxygen: undo the crap Doxygen does to inline namespaces.

Like, COME ON, WAS THAT "CONVENIENCE FEATURE" REALLY WORTH THE EXTREME
ADDED PAIN FOR EVERYBODY ELSE??? Fuck me.

documentation/doxygen: this bug with includes happens only on < 1.8.20.

documentation/doxygen: use a correct condition in the test.

It's broken like that in 1.9.7 already. That's what I get for pushing
09ddeebf4e77b8912bd8c914c5f75b25dd79d8a1 to master at 4 AM.

documentation/doxygen: Doxygen 1.11 can already produce <sect6>.

What an amazing piece of thing.

documentation/doxygen: work around Doxyen stupidly making XMLs useless.

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.

documentation/doxygen: avoid hitting the typedef dedup bug in tests.

https://github.com/doxygen/doxygen/pull/11141

Sigh. I'd really like to have at least one Doxygen version newer than
1.8.18 on the CI, but it's a minefield because my tests work as designed
and hit each and every regression and silly bug.

documentation/doxygen: adapt this test file to whitespace normalization.

The latex output is extremely random so I ignore those tests locally,
yet this particular bit is what 50a7fc5324198f45cde042c87c7a0b4f651b3d25
should have contained also.

documentation/doxygen: two more ElementTree deprecation warnings.

Missed those in 2588ef1a9a5420fa6b0dc39769ce582ce5dc5bd3.

m.plots: replace hashes in test files before comparing.

Similarly to what I did for doxygen, the damn thing now has hashes
differing even between machines. How the hell is one supposed to make
reproducible builds with that, I don't know.

The 3.4 variant got removed, because it differs from 3.2 only in those
hashes, so it isn't needed anymore. Now I can finally unpin it from 3.7
on the CI and stop being afraid that it changes again with 3.9.3.

documentation/doxygen: use a type with known stable hash in a test.

Because every const, < or > matters with this thing. Every new release
is different hashes, FFS. This handcrafted name fortunately has the same
URL hash in both 1.8.16 and 1.12.

documentation/doxygen: superfluous } in a test.

KDevelop complains, Doxygen didn't even notice this was a bug I guess.

documentation/doxygen: omit filename in anchors to the page itself.

I'm already doing that for all links coming from the template
(crosslinks between member lists and detailed info, section heading
links etc.) but so far it wasn't done for links and references contained
in Doxygen comments themselves.

That not only makes the generated files smaller, especially when there's
a lot of cross-references with large namespace docs full of functions
and typedefs, but also makes the output consistent between 1.8.16 and
1.12, which is why I'm doing this in the first place.

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.