[Development] Towards a Qt 5 beta: Documentation

[Sivan Greenberg]

On Thu, Apr 12, 2012 at 4:12 PM,  <casper.vandonderen at nokia.com> wrote:
> TL;DR: We need to change the way Qt does documentation. A lot of things
> will change and we need help from everybody.
>
This is granted, but as the whole Qt5 process looks, this will be for the good.

> As mentioned by Lars: We should make sure the quality of the documentation
> for Qt 5.0 is as high as possible.
>
The framework is amazing, I'm keen to help the effort to enable more
and more people to experience it and exploit it for their needs. Docs
are instrumental in that (as I mentioned before to anybody who would
listen ;)).

> To get and keep our documentation in shape for Qt 5.0 and beyond I think
> we will need to tackle the following problems....
> .....4.  The QDoc commands and functionality are not known well enough by
> people, which causes QDoc errors.

I guess, beyond the fine manual (tm), we could provide cheat sheets
(like mongodb[0] has) and tips blog posts such that this would quickly
change.

I also think it'd be good to have recent qt users to be part of the
review/ approval process. I still odd at some of the docs I use, so I
hereby volunteer.

> 5.  There is no real review process for documentation contributions.
>
There are two use cases here as I see it, to establish a review
process based on actual use:
1. I want to do X , has Doc material Y enabled me to do so?
2. I want to learn how to use Qt-mobility (can't help it. I love this
module) to its fullest - Is there 'The' tutorial that  introduces me
to the subject, and enables me to follow a real-world, working example
in my interface of choice (e.g. QML or Qt/C++) ?

Once we gather some interested parties off the community we can
test-drive docs through 1 and 2 to make sure it is new b friendly.
Again, I'm interested in that - is there a way I can subscribe to
changes for that, be assigned as one of the reviewers for that through
Gerrit ?

> Modularizing the documentation is a process that will move a lot of files
> around and make some things impossible.

Inevitable, but for an extremely good cause.

> The biggest consequence will be that we will have the same dependency
> chain as when compiling the modules.
> E.g. not allow circular dependencies in the documentation. Therefore there
> can be no links from the QtGui documentation to any class in QtWidgets,

My 0.02EU Cents: As I see it, QtGui should have been lean abstraction
away from QtCore  - should not have contained any Widget related stuff
 (this should be in either another widget stack or in the new Qt Quick
components stack) so this makes a lot of sense to me, also from the
API design view.

> from QtWidgets to QtGui will work, since Widgets depends on Gui.
> This will also automatically break "Inherited by:" between classes in
> separate modules in the documentation.

Perhaps there would be a way to make QDoc aware of that? by some new
directive that would tell it where to look for the base?

> I have written down a possible method for modularizing the documentation
> at the end of this email. That should make the whole process more
> transparent.
>
> Issue 3 just needs people to clean up the documentation, writing
> guidelines to get this standard will be published on the Qt Project Wiki.
>
Please post here when this guideline is ready, thanks!

> For issue 4 I would like to point people to
> http://doc-snapshot.qt-project.org/qdoc/ this is the URL of the qdoc
> manual. If everybody follows what is written there and reports bugs about
> inconsistencies in the manual we should have a minimal influx of new qdoc
> errors.

Bookmarked.

> There are problems in qdoc (like not understanding C++ templates/macros
> and C++11 syntax for documenting QObject::connect), but we should not
> start putting Doxygen documentation commands in QDoc when there is a QDoc
> equivalent.
> I am also aware that we still need to change a lot of "old" documentation,
> like replacing all \gui commands with \uicontrol, which is quite a simple
> search/replace.
>

These are QDoc commands I take it? /me goes to do some QDoc manual reading.

>
> Issue 5 needs thought and help from everybody. We will keep the normal
> reviewing process for documentation and we cannot enforce all
> documentation patches to be reviewed by native English speakers/technical
> writers. But when documentation changes we should all pay special
> attention to making it understandable to someone who is new to Qt. This
> has always been the focus of the Qt documentation and I think we should
> try to keep the same standard of documentation going forward.
>
I'm keen to see if I can send a call for help to the greater
community, to see who's willing to take part in a doc review team we
could form on Gerrit, also see my previous suggestion of the use cases
for review.


>
> -- Modularized documentation proposal
> - Individual modules have their documentation in
> /src/[conveniencename]/doc. For example: "/src/corelib/doc". Documentation
> .qdoc files will stay under "src" in that folder, snippets will stay under
> "snippets", etc.
>
To me, documentation is a source just like program code, makes sense.

> - Images will go in /src/[conveniencename]/doc/images, cross-module images
> will not be allowed (unless you copy them into multiple folders).
>
> - The [modulename].qdocconf will be in the top-level directory for the
>
> module. For QtCore this means that the qdocconf file will be
> qtbase/src/corelib/doc/qtcore.qdocconf.
>
> - Documentation output will be put in /doc/html/[modulename]. The whole
> /doc/html/[modulename] folder will be copied to
> QT_INSTALL_DOCS/[modulename]
>
> - For cross-linking we need to do a few things (None of this is
> implemented yet):
> 1. We need to add a "depends" qdocconf variable, where you list the
> modules you depend on. The easiest thing would be to use the full
> modulename, so qtcore instead of just core. This means that you put
> "depends += qtcore" in the qtgui.qdocconf

Ah, that's the replacement for the deprecated 'Inherited' then ?

> 2. We could then implement an -indexdir CLI option/variable which points
> to the directory containing all documentation and let qdoc look for
> /[modulename]/[modulename].index under that folder,
> 3. Then we will have to set-up the .pri files to let indexdir point to
> qtbase/doc/html for the modules in qtbase and QT_INSTALL_DIR/doc for the
> other modules. So when building qtgui qdoc will be called with "qdoc
> -indexdir doc/html doc/gui/qtgui.qdocconf". This should make it find
> /doc/html/qtcore/qtcore.index when you put depends += qtcore in the
> qtgui.qdocconf.
> 4. A problem will occur when you have other repositories that contain
> multiple modules. (such as qtpim and qtdeclarative) So there we need to
> specify 2 -indexdir options, QDoc should check the timestamp when there
> are 2 conflicting index files and use the newest one.
>
You mean when you have 2 modules that 'depend' on a common set of ancestors ?


> - In the case of repositories with only one module we will not have the
> [conveniencename] folder level, so for instance Qt XML Patterns will have
> /doc/qtxmlpatterns.qdocconf
>
> - We will need to add the necessary "make [modulename]-docs" commands etc.
> in .pri files.
>
>
> A working prototype for QtCore can be found in
> http://codereview.qt-project.org/#change,20696 (depends on change 23020
> for compilation). If you cherry-pick that change and run qdoc
> doc/corelib/qtcore.qdocconf in qtbase the output will be visible in
> doc/html/qtcore/. Since QtCore does not depend on anything there is no
> "depends" in the qdocconf necessary.
>
Should give it a look. Since some of this QDoc hacking stuff is a bit
too much to ingest on a first swipe, I'll be up for asking more
questions as I progress through what I can do in my free time- send
here further questions and discussion?

Thanks for your work.

-Sivan