As you might already know, Qt 5.15 is scheduled for release on 19 May, little more than a week from today. This marks the last minor version of Qt5. It also marks the start of what Martin Smith [0] called "a whole new era", as it introduces DocBook as an output format for QDoc.
DocBook is an XML format that started out tailored for technical documentation. Its strength lies in the portability it offers; DocBook can be converted into a range of popular formats, including html, pdf, man pages, and others.
As far as I know, QDoc's DocBook generator represents the largest contribution to QDoc from the open source community yet, and I'm very happy to see the effort that went into it. The author is Thibault Cuvelier, and I would hereby extend my gratitude to Thibault for taking an interest in QDoc and investing the time to develop this feature. I'm also grateful for the effort from several engineers at The Qt Company that supported Thibault with code review and testing the feature.
So how do you get started? It is quite simple. All you need to do is add
outputformats = DocBook
to your documentation project configuration (.qdocconf-file), and you're good to go! You can also have your project generate multiple output formats, if you are so inclined. If you do, you should define the output directory for all formats, like so:
outputformats = HTML DocBook
HTML.nosubdirs = true
DocBook.nosubdirs = true
HTML.outputsubdir = Documentation-html
DocBook.outputsubdir = Documentation-docbook
This will generate the directories Documentation-html and Documentation-docbook and place the output for the respective formats in separate locations.
QDoc’s implementation of DocBook also supports a set of new tags that are not (yet) part of the DocBook standard but have recently been accepted as a contribution to DocBook 5.2 [1]. These tags encode metadata about the code itself. You can enable them by passing the command line option --docbook-extensions when invoking QDoc.
And now? You can grab the latest release candidate of Qt 5.15 if you already want to try this out or wait for the upcoming release - it's getting closer by the day! Let us know what you think of this feature; add a comment below, send me an email, or add a suggestion or bug report on the bugtracker [2]. As the feature is brand new for us, we'd love your feedback. And if you have other ideas that can improve QDoc or the Qt documentation experience, we'd love to hear about that, too - unless you want to follow in Thibault's footsteps and submit your contribution!
--
[0] - https://www.qt.io/blog/the-first-complete-story
[1] - https://github.com/docbook/docbook/issues/111
[2] - https://bugreports.qt.io/
[3] - https://codereview.qt-project.org/
.webp)
