After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 758313 - Make gtk-doc easier to use from build systems other than automake
Make gtk-doc easier to use from build systems other than automake
Status: RESOLVED OBSOLETE
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other Linux
: Normal enhancement
: ---
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2015-11-18 22:30 UTC by Jussi Pakkanen
Modified: 2018-05-22 13:10 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Jussi Pakkanen 2015-11-18 22:30:47 UTC
Currently gtk-doc seems to share some functionality between core gtk-doc binaries and the automake module snippet that drives it. Tracing what commands Make invokes reveals stuff like copying files between source and build trees, copying version.entities to html dirs and so on.

Trying to replicate what it does is difficult, especially since sometimes you need to copy xml and definition files from the source tree to build tree, because gtkdoc seems to do different things based on where said files reside. (Sometimes it does not read them from source tree but does from the build tree.) Some commands also seem to have a requirement that they are executed in a specific directory.

It would make things easier if this complexity could be pushed into gtk-doc binaries so it is there only once and all build systems can just invoke it.

As an example, suppose the project root is at /proj, the header files to scan are in /proj/src, documentation files (proj-docs.sgml and the like) are in /proj/doc and the build tree is at /proj/build.

To generate docs, one should be able to run just one command like this (note that cwd can be anything). I'm using absolute paths, but relative ones should work just the same.

gtkdocv2 --docdir=/proj/doc --outdir=/proj/build/doc --scandir=/proj/src --output-format=html --main-file=proj-docs.sgml [other conf flags here]

The main program should then take care of calling all the subcommands in the proper way.
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2015-11-19 07:14:04 UTC
+1 I think what is now in the makefile has grown historically. But having a single driver (that can be just called gtkdoc) would simplify the usage. In order to get there we can also add more options to the tools and remove code from the makefile (like building commandline args).

So far the motivation for the granularity and using make was to not run steps that don't need to be run, but I don't see anything that would make it impossible for the main driver script to skip not needed steps.

FYI, I just added cmake support to gtk-doc

If you think you could give this a try, that'd be awesome. We can chat also on this in irc (#gtkdoc on gimpnet)
Comment 2 Yeti 2015-11-19 07:37:52 UTC
Currently it is possible to modify the build steps and insert additional preprocessing and postprocessing between them -- thanks to the tools being separated and run explicitly from a Makefile rule.  Your suggestion will destroy this possibility unless it is possible to add scripts anywhere that have access to all the gtk-doc parameters...

Now, if someone writes such a gtkdoc script that wraps the separate tools and works for trivial projects, why not.  Evidently there are people who prefer a monolithic magic command to a toolset.  However, I am afraid if such script becomes the official interface, people will start breaking the individual (now ‘internal’) tools.

At present projects do not require gtk-doc on the target system to install documentation, they can carry prebuilt HTML as a fallback.  If you want to avoid any logic in the Makefiles, this also will be destroyed.

By the way, there are no gtk-doc binaries.
Comment 3 Jussi Pakkanen 2015-11-19 10:48:50 UTC
Keeping the commands separate is fine, but the problem is that the way they work is not documented anywhere. By this I mean things like:

- what files need to be in the build dir and which are read from the source dir (foo.types, for example, does not seem to be read from source dir, other ones are)

- why is foo-docs.sgml sometimes different in the build dir and sometimes the same, why does gtkdoc fail with weird errors instead of reporting this

- where are version.properties and the like searched from, can you give additional paths (the makefile seems to copy them to html dir during generation and then delete them, which is weird)

- which directories must each specific command be run in (preferably, update them so that they can be run from anywhere)

And so on.
Comment 4 Stefan Sauer (gstreamer, gtkdoc dev) 2017-03-25 19:16:37 UTC
A late comment ...

(In reply to Jussi Pakkanen from comment #3)
> Keeping the commands separate is fine, but the problem is that the way they
> work is not documented anywhere.

There is a .dot file in docs, that documents which files are build from which. This was one of my first contributions to gtk-doc.


> By this I mean things like:
> 
> - what files need to be in the build dir and which are read from the source
> dir (foo.types, for example, does not seem to be read from source dir, other
> ones are)

This is still someone an issue. All tools should get a file-search-path consisting of builddit:srcdir:... (or just one if they are the same). Right ow this is somewhat ad-hoc.
> 
> - why is foo-docs.sgml sometimes different in the build dir and sometimes
> the same, why does gtkdoc fail with weird errors instead of reporting this
If it fails, please file a bug.

> 
> - where are version.properties and the like searched from, can you give
> additional paths (the makefile seems to copy them to html dir during
> generation and then delete them, which is weird)
There is no version.properties file as part of the file gtk-doc uses.
> 
> - which directories must each specific command be run in (preferably, update
> them so that they can be run from anywhere)
> 
> And so on.
Comment 5 GNOME Infrastructure Team 2018-05-22 13:10:40 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to GNOME'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.gnome.org/GNOME/gtk-doc/issues/34.