This is a known and not so simple to fix issue as currently the plugins generation system is quite linked to autotools.

Instead I am porting GStreamer documentation to hotdoc[0] on my `hotdoc` branches around here[1].

You can find the current result here:

  https://thiblahute.github.io/GStreamer-doc/

It is almost done but I have patches to get merged in hotdoc and need to fix some details all around still, we are planning to discuss that work for the GStreamer hackfest in two weeks :-)

[0] https://github.com/hotdoc/hotdoc
[1] https://github.com/thiblahute?utf8=%E2%9C%93&tab=repositories&q=gst&type=&language=

*** Bug 796870 has been marked as a duplicate of this bug. ***

I updated that port to hotdoc, we got a pre-release of the required Hotdoc out I proposed the hotdoc meson module upstream already (hopefully it gets merged soon :-)) and I have the rendered documentation here:

https://thiblahute.pages.freedesktop.org/gst-build/?gi-language=c

Would be nice if you could have a look and let me know what you think what else you would like etc...

The GStreamer branch are still at the same place (and are quite clean/ready to be merged).

> The GStreamer branch are still at the same place (and are quite
> clean/ready to be merged).

Could you link the repo/branch you are refering to? The "hotdoc+plugins" branch on your gstreamer core github does not look very clean :)

You mean https://github.com/thiblahute/gst-docs/commits/hotdoc ?

OK, that should be the right list: :-)

 * https://github.com/thiblahute/gst-build/tree/hotdoc
 * https://github.com/thiblahute/gst-docs/tree/hotdoc
 * https://github.com/thiblahute/gstreamer/tree/hotdoc
 * https://github.com/thiblahute/gst-plugins-base/tree/hotdoc
 * https://github.com/thiblahute/gst-plugins-good/tree/hotdoc
 * https://github.com/thiblahute/gst-plugins-bad/tree/hotdoc
 * https://github.com/thiblahute/gst-plugins-ugly/tree/hotdoc
 * https://github.com/thiblahute/gst-libav/tree/hotdoc
 * https://github.com/thiblahute/gst-devtools/tree/hotdoc
 * https://github.com/thiblahute/gst-editing-services/tree/hotdoc
 * https://github.com/thiblahute/gst-rtsp-server/tree/hotdoc

Ah, I haven't removed gtk-doc support, I think we can keep having them until we have autotools support, not sure what you prefer?

I'm a bit confused looking at the repos (e.g. gstreamer/hotdoc) - what's the plan exactly?

My plan was to move *everything* docs related including API/plugin docs generation into the gst-docs module.

This requires a few things beside the api ref / plugin ref generation, such as also generating a devhelp version of all the docs in addition to html (but aiui that's already possible?)

And then we ship a gst-docs tarball basically.

We would remove gtk-doc stuff from the other modules when we drop autotools.

But we will not add hotdoc support to the other modules as I see it.

Well, the doc still is in each repo and can be built separately, gst-docs is just aggregating everything in one place.

Shipping a gst-docs tarball is easy to do with that setup.

The hotdoc/ directory is just where I have the infos about the plugins and the definition of how to build the doc for plugins/libs basically, that info is reused (through meson subproject goodness) in gst-docs to generate a coherent doc for all modules. Currently `ninja -C build/ install`  install the doc for each module, I can revert that part if you think it is better to just "advertise" the aggregated doc and distribute it in a tarball separetly (I think that would be a good idea in the end).

Now the way it is done is also good so that when developing in -good for example you will be able to generated the doc for the plugin you care (to check) with ninja -C build docs/hotdoc/thepluginicareabout-doc

Makes sense?

So this is basically the infrastructure and how things work together currently:

In each module, we have a set of Hotdoc meson targets which build docs for different components (1 per lib and 1 per plugin). Those are referenced by the `libs_doc` and `plugins_doc` variables in the meson file so they can be reused/referenced from outside the module (be aggregated in gst-docs).

In gst-build we have a list of built projects which is passed to gst-docs.

In gst-docs, we go over the list of built subprojects and retrieve the targets for all the doc from the various subprojects, aggregating the documentation in a single sitemap.

---

To build the GStreamer plugins documenation we have a `hotdoc-plugin-inspect` binary which basically takes a list of plugins `.so` and outputs json. Then we have a hotdoc-plugin that consumes the json, updates it with informations from previous runs (I worked on making sure it is all ordered and stable) and renders the documentation for the plugins. The json file doesn't contain the doc from comments. Currently updating the json is done at the same time as building the doc, it can easily be done in a dedicated run_target if required/preferred (I am not sure it is a good idea).

I added a `release` target that generates a tarball like: https://nextcloud.igalia.com/index.php/s/WC5E9ybTHQCFQXc - it contains all the doc and required files to be used inside devhelp.

I just cleaned up the branches and I think it is almost ready for merging now. Would be nice if someone could review.

(List of branches is available in comment 6: https://bugzilla.gnome.org/show_bug.cgi?id=782176#c6)

-- GitLab Migration Automatic Message --

This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/gstreamer/gstreamer/issues/233.