Contributing documentation to QtWebKit

UNDER CONSTRUCTION! This wiki page contains the information that is relevant for technical writers contributing documentation to QtWebKit.

QtWebKit currently comes with a lot of documentation for C++ developers, and we'd like to extend the documentation also for web developers.

The documentation sources are in qdoc format, stored together with the source code in the WebKit SVN. Documentation contributions are submitted to the project similarly as source code contributions -- for instance, documentation changes need to be reviewed before they are committed.

The C++ API documentation is included in line in the C++ source files. Standalone documentation articles are in the WebKit/qt/docs directory.

The qdoc3 tool

The qdoc3 markup is a simple wiki-like format. The qdoc3 tool is documented here: ​http://qt.gitorious.org/qt/pages/DocManual.

For Windows users, the easiest way to get the qdoc3 command line tool is to install the Qt SDK for Windows and add Qt's bin directory to the system's PATH environment variable in the Windows Control Panel. For instance, if you install Qt SDK version 2010.3 to the default location, the qdoc3.exe tool will be in C:\Qt\2010.03\qt\bin.

On Mac OS X, the qdoc3 binary has not been previously included in the Qt SDK, but as of Qt 4.7 Beta II (to be released soon at the time of writing), the qdoc3 binary is included in the Qt SDK. After installation, qdoc3 should already be in the PATH.

Installing git

In this wiki, we describe how to work with the git version control system and the mirror of the WebKit SVN repository hosted at ​Gitorious.org.

Before you can use Gitorious.org, you need to install git on your computer. Here are some instructions for git installation on different platforms: ​http://git-scm.com/download

• On Windows, you can get git by installing Cygwin (from the link above). Cygwin is a distribution for several different tools, so during the installation, Cygwin will ask you to select the packages you want to install. Make sure you install at least the git package, and possibly also git-gui, a graphical user interface for git. The git package may not be installed by default. If you want to use a regular command prompt or the Qt command prompt on Windows, you need to add the bin directory of the Cygwin installation to your PATH environment variable. The default location is C:\cygwin\bin.

After installing git, you can verify your installation by typing git on the command line. If git has been installed and included in your PATH, you will see a list of most commonly used git commands.

Checking out the sources

Since the documentation is stored together with the source code, also technical writes need to check out the sources. Open a command prompt, go to your working directory for QtWebKit documentation, and type the following command:

git clone git://gitorious.org/webkit/webkit.git

Cloning the repository can take some time, so please be patient.

Git repositories can have several branches. However, by default you should have the master branch of this repository checked out, which works fine for contributing documentation to QtWebKit.

If you want to make sure you're using the master branch, you can see the remote branches you just fetched with this command:

git branch -r

And to switch to a branch simply use git checkout branchname

Building the documentation articles

To build the QtWebKit documentation simply run make docs in your build directory, i.e. WebKitBuild/Release. The output will be generated in HTML in the doc/html subdirectory.

If you also need to work on the C++ API documentation that refers to the Qt API documentation, then you need to build Qt from sources. See ​http://trac.webkit.org/wiki/QtWebKitContrib for more information.

Submitting a documentation contribution

Documentation is contributed to the WebKit SVN (the trunk of the project). By default, the documentation change will then be included in the next QtWebKit release that is branched off from the trunk. It is also possible to "cherry-pick" documentation changes to previous versions of QtWebKit (see below).

When using the git repository to access the sources, the steps to submit a patch are roughly as follows. Please see the WebKit project's page about ​contributing for more information.

• Make your changes in the webkit source code directory. Typically, you would change existing qdoc files or create new qdoc files.
• Run the WebKitTools/Scripts/prepare-ChangeLog script to create an entry for your changes in each relevant ChangeLog file.
• Edit the ChangeLog files reported by the prepare-ChangeLog script:
  • If you work on a task without bug report on bugs.webkit.org yet, create a bug report. Use the severity "Enhancement" if your patch is an improvement and not related to a bug.
  • Add a short description and paste the bug URL below it. Add an extra line and a detailed description if necessary.
  • Precede the short description with "[Qt]" since your documentation patch is specific to the Qt port of WebKit.
  • The description text should be the same in all ChangeLog files.
  • Keep the "Reviewed by NOBODY (OOPS!)." line in the ChangeLog files, it will be edited by the bot or person that will commit your fix.
• Do a git diff > patchname.patch to create your patch (use --cached if you first did a git add to put your changes in the git index)
• Attach the patch to the bug report, set the review flag to '?' and the commit-queue flag to '?'
• Wait :)

Having your documentation contribution cherry picked to a previous QtWebKit release

TBD

Communication

We can use the QtWebKit ​webkit-qt Mailing List and the #qtwebkit IRC channel on freenode.net to discuss documentation, too.