Hawkmoth runs from the build-directory, which makes sense. However, we
set up a bunch of source-relative include paths, which will break if we
don't build in-tree.
Let's make these relative to the source-tree instead. We can deduce the
source-root from the parent directory of the current file.
Reviewed-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Eric Engestrom <eric@igalia.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11494>
Use the hawkmoth c:auto* directives to incorporate isl documentation.
Convert @param style parameter descriptions to rst info field lists.
Add static stubs for generated headers. Fix a lot of references, in
particular the symbols are now in the Sphinx C domain, not C++
domain. Tweak syntax here and there.
Based on the earlier work by Erik Faye-Lund <kusmabite@gmail.com>
Reviewed-by: Erik Faye-Lund <erik.faye-lund@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/24507>
Use the hawkmoth c:auto* directives to incorporate nir documentation.
Convert @param style parameter descriptions to rst info field lists.
Add static stubs for generated headers. Fix a lot of references, in
particular the symbols are now in the Sphinx C domain, not C++
domain. Tweak syntax here and there.
Based on the earlier work by Erik Faye-Lund <kusmabite@gmail.com>
Reviewed-by: Erik Faye-Lund <erik.faye-lund@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/24507>
Hawkmoth is a Sphinx-extension that uses Clang to directly parse C code
for automatic documentation of C/C++ code, similar to what Doxygen does.
However, Doxygen is rather clunky to integrate into the build process,
so let's start switching over to Hawkmoth instead.
As Sphinx does not have syntax for describing parameter direction, add
an rst_prolog with rst replacements for them.
Reviewed-by: Jani Nikula <jani@nikula.org>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/24507>
I'm not sure why I picked html_extra_path instead, as it's meant for
slightly less directly related files than what html_static_path is for.
So let's switch. It shouldn't make much of a real-world difference, but
should make it a bit easier to understand what this is about.
Reviewed-by: Corentin Noël <corentin.noel@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25585>
These redirects are all fine. I don't think we want to apply them,
because they are more about implementation details on the target site.
So let's just mark them as OK. They cause no harm.
There's also some redirects that are all about authentication. We also
don't want to apply these, because they would break the links.
Reviewed-by: Corentin Noël <corentin.noel@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/25585>
There's a *lot* of relnotes, and we don't really actively maintain them.
Let's drop linkchecking them to speed things up a bit.
This does a whole lot of nothing unless you have Sphinx 4.4 or newer.
Reviewed-by: Eric Engestrom <eric@igalia.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/19574>
GitLab Pages has added a feature to do proper HTTP redirects, which
are genreally better than the HTML redirects we currently use.
Unfortunately, it doesn't support redirecting to other domains, all
paths must start with a slash. So there's sadly *one* redirect this
doesn't work for. So let's leave that one using a HTML redirect, and
use HTTP redirects when we can.
Reviewed-by: Eric Engestrom <eric@engestrom.ch>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/14369>
This commit mostly just adds the framework required to scrape
documentation out of the ISL sources and headers. The method chosen
here is a combination of doxygen and breathe (a sphinx extension for
doxygen integration). I'll freely admit that doxygen is pretty terrible
but it seems like the best option we have available to us today.
Acked-by: Emma Anholt <emma@anholt.net>
Acked-by: Daniel Stone <daniels@collabora.com>
Acked-by: Erik Faye-Lund <erik.faye-lund@collabora.com>.
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11366>
No other drivers use the vendor in the title or path, so it seems better
to not do this for the vmware-guest driver as well. So let's rename it
to SVGA instead. The actual text itself makes it clear enough what it is
about.
This makes it stand out less in the toctree.
I chose the name "WMware SVGA3D", because that's less ambigious than the
"SVGA"-alternative, and was requested by VMware people.t
Reviewed-by: Alyssa Rosenzweig <alyssa.rosenzweig@collabora.com>
Reviewed-by: Chia-I Wu <olvaffe@gmail.com>
Acked-by: Jose Fonseca <jfonseca@vmware.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11109>
The idea of having a single file containing the ToC is not really how
things are done in Sphinx, and kinda makes it harder to structure
documentation more naturally. This was just something I did to mirror
what we used to do for the old HTML-only version of the docs, to ease
the transition and to de-clutter index.rst.
Now that the transition is far behind us, and index.rst is much cleaner,
we can finally start inlining this.
In the long run, I expect most of these to be moved to separate "chapter
articles" that summarize what these topics are, and thus disappear from
here.
Reviewed-by: Eric Anholt <eric@anholt.net>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/7709>
I actually had never found these, buried under Developer Topics -> Gallium
-> Drivers. Given that driver documentation contains not just gallium
driver documentation but also end-user information, bring it to a much
more prominent location between User Topics and Developer Topics at the
top level.
Reviewed-by: Erik Faye-Lund <erik.faye-lund@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/7174>
It's easier to contribute to the documentation if we have links to the
document on GitLab. This will allow people to easily edit docs, or to
realize where in the source-tree they are without having to search.
Reviewed-by: Eric Engestrom <eric@engestrom.ch>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/6742>
The original issue asked for all the keys in a single file, but I didn't
do that because it's much easier to manage and verify the keys as
separate files, but sphinx doesn't provide a way to expose a folder so
we'd need to create an index.html and have it list all the keys
manually, which is very error prone.
At this point, we might as well just concatenate the keys and expose
a single file, so let's do that.
Signed-off-by: Eric Engestrom <eric@engestrom.ch>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/5568>
Unfortunately, it doesn't seem like there's a way to have sphinx copy
this without moving the files, becasue html_extra_path doesn't copy the
directory itself when given a directory, only files inside and
subdirectories.
Reviewed-by: Eric Engestrom <eric@engestrom.ch>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/4630>
