documentation/python: test external summary for a submodule.

Fails. It's amazing how far can some bugs go unnoticed.

documentation/python, m.sphinx: hook for parsing docstrings.

Centuries of work and research later, this gem is done. Yay!

m.sphinx: don't overwrite the docs gathered so far.

This won't work well when more plugins are involved or the directives are
used to parse docstrings. Also updated the plugin docs to not suggest this
practice.

doc: improve the python docstring info.

doc: move python documentation plugin internal docs later in the page.

These are not so useful for users, and the stuff that followed them was
too buried.

documentation/python: minor cleanup.

documentation/python: fix a copypasta in a test.

documentation/python: unconditionally go through reST for everything.

Well, of course not forcing reST formatting on plain docstrings -- just
having a single code path because that makes integrating 3rd party
processing easier. Results in absolutely no changes to test files, which
is absolutely amazing.

documentation/python: support documenting particular function overloads.

documentation/python: include params in search only for overloads.

And not unconditionally for all pybind functions. Makes the search data
lighter and is more consistent with pure Python code (and with the future
support for the @overload decorator).

documentation/python: detect overloaded functions already at crawl time.

But don't change the behavior in any way -- just that the consumers should
be aware of the distinction.

documentation/python: poison entry types that shouldn't go into search.

Spent a while using OVERLOADED_FUNCTION in a few places just to discover
it wasn't meant to be used there.

documentation/python: provide both type and type with links everywhere.

Makes it possible for templates to use those in different cases (such as
link alt text) and also unblocks the possibility to have separate docs for
function overloads (in the next commits).

documentation/python: special handling for self only if it's first.

I doubt anyone sane will name any other function parameters like that, but
let's be sure.

documentation/python: don't annotate free pybind function as staticmethods.

Wasn't visible in the output until now because we didn't have detailed
docs for those. But now it will be.

documentation/python: parse more than just first docstring paragraph.

Next step is to allow those to get processed using plugins.

documentation/python: minor cleanup.

documentation/python: verify that HTML escaping is done for pybind as well.

It is, even though I felt like it wasn't. Good to have to avoid
double-escaping accidents in the future.

documentation/python: whoops, enum detailed docs weren't rendered.

doc: fix for order-dependent processing, again.

theme: no, this PR is still not merged yet.

m.sphinx: ugh, I still need to support Python 3.5.

m.sphinx: ability to create intersphinx inventories as well.

m.sphinx: utility to pretty-print the inventory files.

The builtin sphinx tool is beyond useless. FFS.

m.dot: doc++

documentation/python: implement context-relative linking.

I didn't change much, but the amount of research needed to verify that I'm
indeed doing it (mostly) correct was extreme. There's a pathological case
inside a named subclass where I'm doing it differently than Python itself,
but I don't expect this to be hit very often, so postponing until later.

The tests also assert inside the function definitions (and those functions
get called) to verify we're indeed doing (mostly) correct stuff.

documentation/python: correctly link all type annotations as well.

documentation/python: prefix pybind's annotations with the typing module.

So it's consistent with pure Python annotations.

documentation/python: integrate tighter with m.sphinx.

The :ref: from m.sphinx can now link to internal types, while external
types provided by m.sphinx are now also linked to from all signatures.

Yay, I'm so happy about the design of this.

documentation/python: add implicit kwargs to all plugin hooks.

So they are future-proofed when new arguments are added. Need also *args
because pelican passes things unnamed.

documentation/python: added a post-crawl hook and exposed name map.

So m.sphinx can use it to add the internal names to its own search index
and also make an inventory for it.

documentation/python: yup, yet another variant of builtin math docstrings.

documentation/python: save URL to all entries to make linking easier.

documentation/python: revisit None in function return type annotations.

Until now it was ignored in pybind return annotations as it seemed to be
superfluous. OTOH, while the pybind function is fully annotated, it's
often not clear which function comes from pybind and which from pure
python code, meaning it's not clear if the return type is None or the
return type annotation is just missing.

Additionally, the pure python annotations were showing None as NoneType,
which is too verbose. According to PEP484 type(None) and None are
equivalent, so patching the output to show None instead of NoneType,
making it also consistent with pybind.

documentation/python: thanks to fixed reST higlighting I see this is dead.

documentation/python: bad documentation copypaste? probably.

documentation/python: minor cleanup.

m.dox: minor cleanup.

m.code, m.math: test & fix nested backticks in interpreted roles.

Broken when fixing backslash support.

m.dox: doc++

m.sphinx: implement intersphinx read support.

Intersphinx write support next.

documentation/python: implement documenting function params and return.

Did not expect I would need to patch Docutils for this because nobody had
this use case since its initial commit in 2002. How the heck is Sphinx
doing this, are they replacing Docutils internals too?!

documentation: add an actual diagnostic to this assert.

Seems to be hit quite often, so make it helpful.

css: make .m-diary left padding large enough to fit a short date as well.

And remove the extraneous margin -- which basically makes it look
roughly the same as before, but without uglily wrapped things.

Doc++

documentation/python: added TODOs for enum value docs.

documentation/python: support external docs for all stuff.

And also detailed docs for enums, functions, properties and data.

doc: remove outdated / redundant info.

documentation/python: um, why don't I use a function here?

Add file encoding to .editorconfig.

doc: Python doc generator *can* search now.

documentation/doxygen: fix last remaining use of deprecated name attrib.

documentation/python: hook up the search.

documentation: trim spaces from the right only if nothing is found.

With unconditional trimming it was not possible to narrow down results
for page titles containing spaces (or subpages, which are separated by
double right arrow surrounded by spaces).

documentation: reuse the saved searched string instead of creating it again.

This avoids duplicating the trimming/decoding logic.

documentation: provide autocompletion in UTF-8 as well.

The search() function returns the result list in UTF-8, but the
autocompletion was not. And of course renderResults() assumed it was in
UTF-8 and decoded it from UTF-8 *twice*. This wasn't discovered until
now because I had no pages with UTF-8 names apart from the test (which
doesn't test the UI stuff).

documentation/doxygen: insert also pages with all prefixes.

Not sure why there was an exception. This makes it practically
impossible to search for subpages.

css: highlight active documentation entries the same as sections.

For Python code, many names will have just the entry without any
detailed docs and it's hard to see where on the page it is if it's not
selected. The same works for Doxygen, of course.

documentation/doxygen: move entry ID to the <dt> element.

And it's no longer the deprecated name attribute, but rather an id.

documentation/python: move entry ID to the <dt> element.

Fancy new stuff incoming!

documentation: trim overly long search results even more.

The function name should be shown fully, ideally together with a
recognizable prefix.

documentation: properly show 100+ when having more results that can fit.

This got accidentally broken in 8bdb844ceb547d8ca3156ef815de9603e51a598a
when implementing the Tab autocompletion. Unfortunately I can't really
auto-test the UI code :/

documentation: re-render symbol count if search box gets shown again.

The (stale) count of found symbols was preserved there even though the
search box got emptied again. Also deduplicated the code a bit.

documentation: make it possible to have more than 128 results for a node.

Python's __init__ is the main offender, the (currently very barebone)
Magnum Python bindings have 340 results for __init__. This change is
based on the assumption that nodes with extreme amount of results on the
other hand don't have many children, so we can steal some bits from the
child count instead. Now it's either up to 127 results and up to 127
children or up to 2048 results and 16 children.

documentation: doc++

documentation: make the general search tests backend-independent.

It stays C++-specific, but since the implementation doesn't care about
the language, it's okay.

documentation/python: wtf, why None and why not [].

This was *sometimes* failing during the test, with Jinja complaining
that None is not iterable. But not all the time, for some reason.

documentation/python: extract the name shortener utility.

documentation/python: minor cleanup.

documentation/python: pass the whole entry to documentation extractors.

Compared to basically unpacking the entry and passing all of it as
separate arguments this makes it easier to get the page URL and in the
future also other stuff.

documentation/python: save URLs of crawled classes, modules and pages.

Makes link creation much simpler later.

documentation: search data format version 2.

Instead of having a hardcoded mapping from flags to type names and
associated classes on the JavaScript side, which was very C++-specific,
the new format now moves this mapping directly into the search data.

It's a new section at the end, for each type index containing CSS class
ID (which is still hardcoded, but that's not language specific anyway)
and an UTF-8 name that's displayed in the label. For C++ this makes the
search data file size 107 bytes larger, which isn't significant by any
means.

documentation: remove dead code.

documentation: ensure the extra arguments are always passed as keywords.

documentation: encode format version into search data filename.

The browser having a stale data (and a stale script) cached is okay-ish
as things still mostly work, but having a stale data with a script
expecting a new version or vice versa is *bad*, so prevent that by
having the script always download file of the exact version it expects.

This is a bit less useful with docs served from local filesystem (as
the filename is encoded in HTML pages rather than in the script), but
there I don't assume the browser is doing much caching so that should be
okay.

documentation: add sanity checks for always-defined template variables.

documentation: make the search test data diffable.

documentation: first step to make the result types backend-specific.

The type is now a part of the doxygen script and is added as plain bits
to ResultFlag. Next step is encoding the type mapping to the search data
and then reading that back in the JS frontend.

documentation/doxygen: update JS tests and ensure it doesn't happen again.

Ugh. The flags got reordered in 1a10e178fbf4d370ba1ae3026e5492c757cfef2e
(HALF A YEAR AGO!) but the JS test data were never adapted to that, so
the JS test was still working with the old stuff.

The Travis CI job was modified to execute the python script during
the JS test run and verify there's no git diff after that.

documentation: move search-related stuff into a dedicated module.

So it can be used by the Python doc generator as well. Wanted to put it
into __init__.py, but Guido disagreed with that, so I can't.

m.math, documentation: update math support for dvisvgm 2.6.3.

It reorders all XML attributes for no reason. Ugh I hate this.

m.math: ensure cache file is reset when cache is not used.

Otherwise tests run in batch can sporadically fail.

m.qr: patch the output to be consistent between Travis any my Python 3.7.

package/ci: build for Python 3.7 and pybind 2.3 as well, drop 3.4 build.

Drop Python 3.4 support.

It was EOL'd in March 2019 and I don't want to bother with it anymore.

documentation/python: handle also getset descriptors.

Ugh enough with those weird things already.

documentation/python: properly handle inspection of slot properties.

There's no fget/fset/fdel for those and we also can't __doc__ them.

documentation/python: reduce annotation test to just parsing, not links.

Type links are tested in test_inspect.TypeLinks.

documentation/python: reduce needed test boilerplate.

Will do the same for doxygen, plugin and theme tests too, but later.

documentation/python: warn when a type link should (but isn't) resolved.

Could help with figuring out what types were accidentally omitted from
the docs.

documentation/python: attrs does bad things and I'm not happy about that.

documentation/python: further improve type annotation support.

This is an awful mess, ffs. Like if nobody designed this with
introspection in mind.

documentation/python: minor clarification in a test.

documentation/python: properly handle invalid annotation types.

Such as using a tuple instead of Tuple or putting a function there
instead of a type.

documentation/python: properly handle nested pybind signature parse errors.

I still feel uneasy throwing exceptions. But eh.

documentation/python: properly parse pybind's Callable annotations.

documentation/python: clean up redundant imports.

documentation/python: test pybind readonly properties, for completeness.

documentation/python: support write-only properties.

Supported by Python through a slightly crazy syntax and in pybind11
since 2.3.

documentation/python: unify and improve formatting of values.

Such as function default values or data values. Mainly done in order to
turn enum values into links. Also ensuring the value is always HTML
escaped.