Bug 106186 - doxygen_to_devhelp: should produce index format v2
Summary: doxygen_to_devhelp: should produce index format v2
Status: RESOLVED FIXED
Alias: None
Product: dbus
Classification: Unclassified
Component: core (show other bugs)
Version: git master
Hardware: Other All
: medium minor
Assignee: Simon McVittie
QA Contact: D-Bus Maintainers
URL:
Whiteboard: review+
Keywords: patch
Depends on:
Blocks:
 
Reported: 2018-04-23 10:34 UTC by Simon McVittie
Modified: 2018-04-23 17:29 UTC (History)
0 users

See Also:
i915 platform:
i915 features:


Attachments
[1/2] doxygen_to_devhelp: Make the API reference the front page (899 bytes, patch)
2018-04-23 10:35 UTC, Simon McVittie
Details | Splinter Review
[2/2] doxygen_to_devhelp: Produce Devhelp index format v2 (1.98 KB, patch)
2018-04-23 10:35 UTC, Simon McVittie
Details | Splinter Review

Description Simon McVittie 2018-04-23 10:34:22 UTC
Apr 23 10:59:02 espresso devhelp[7590]: The file 'file:///usr/share/gtk-doc/html/dbus/dbus.devhelp.gz' uses the Devhelp index file format version 1, which is deprecated. A future version of Devhelp may remove the support for the format version 1. The index file should be ported to the Devhelp index file format version 2.
Comment 1 Simon McVittie 2018-04-23 10:35:02 UTC
Created attachment 138995 [details] [review]
[1/2] doxygen_to_devhelp: Make the API reference the front page
Comment 2 Simon McVittie 2018-04-23 10:35:28 UTC
Created attachment 138996 [details] [review]
[2/2] doxygen_to_devhelp: Produce Devhelp index format v2

The old version-1 format is deprecated and now produces warnings.
Comment 3 Philip Withnall 2018-04-23 13:00:23 UTC
Comment on attachment 138995 [details] [review]
[1/2] doxygen_to_devhelp: Make the API reference the front page

Review of attachment 138995 [details] [review]:
-----------------------------------------------------------------

Sure, r+. Do you want to put some rationale in the commit message?
Comment 4 Philip Withnall 2018-04-23 13:04:19 UTC
Comment on attachment 138996 [details] [review]
[2/2] doxygen_to_devhelp: Produce Devhelp index format v2

Review of attachment 138996 [details] [review]:
-----------------------------------------------------------------

r+. You might want to add dbus.devhelp2 to doc/.gitignore too, though, since the old file is in there.

The XSL changes seem reasonable, but I can’t find a useful reference for either v1 or v2 of the format, so I can’t verify the XSL changes are correct or complete.
Comment 5 Simon McVittie 2018-04-23 16:44:59 UTC
(In reply to Philip Withnall from comment #3)
> Sure, r+. Do you want to put some rationale in the commit message?

I added:

    The tutorial is not necessarily a great entry point for the libdbus
    documentation: it's infrequently updated, and we should probably have
    the "If you use this low-level API directly, you're signing up for some
    pain" message from the API reference show up in devhelp more immediately.

(In reply to Philip Withnall from comment #4)
> You might want to add dbus.devhelp2 to doc/.gitignore too

Done

> The XSL changes seem reasonable, but I can’t find a useful reference for
> either v1 or v2 of the format, so I can’t verify the XSL changes are correct
> or complete.

It resembles GStreamer's gtk-doc-generated index and no longer provokes warnings in devhelp - good enough! :-)
Comment 6 Simon McVittie 2018-04-23 17:29:34 UTC
Fixed in git for 1.12.8 and 1.13.4.


Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.