Contributing documentation to QtWebKit

UNDER CONSTRUCTION! This wiki page contains the information that is relevant for technical writers contributing documentation to QtWebKit.This page covers how to contribute standalone articles and changes to the existing articles. Contributing C++ API documentation is not covered here.

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 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.0, the qdoc3 binary is included in the Qt SDK. After installation, qdoc3 should already be in the PATH.

Getting access to the existing documentation source files

The simplest way to get the existing documentation files is to use the web interface of ​http://svn.webkit.org/repository/webkit/trunk/WebKit/qt/docs/. That URL points to the WebKit/qt/docs directory where all the Qt specific documentation articles are stored.

A convenient way to get the whole documentation directory tree is to use SVN and check out the docs directory.

Building the documentation articles

TBD: the qdoc command for building the articles.

Including an explicit license

For new document articles, you must include the following explicit license text at the bottom of the article:

This document and any changes thereto are licensed under the Creative Commons Attribution-Share Alike 2.5 License Agreement.

The full license text is available here: ​http://creativecommons.org/licenses/by-sa/2.5/legalcode. To the extent any examples and code snippets are referenced in this document, such examples and code snippets are licensed under the BSD license: www.opensource.org/licenses/bsd-license.php.

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). In some cases, documentation changes are needed in a certain release branch only.

• Make your changes. Typically, you would change existing qdoc files or create new qdoc files.
• Create a bug in the WebKit bugzilla. Use this template as the starting point: ​http://webkit.org/new-qtwebkit-bug.
  • Leave the component as "New bugs".
  • Use the severity "Enhancement" if your patch is an improvement and not related to a bug in documentation.
  • Select 528+ (Nightly build) as the version
  • Enter "Ademar Reis" as the assignee
  • As the reporter of the bug, you will automatically receive email updates when the bug changes, for example when there are comments from reviewers. If you'd like a colleague or a mailing list to receive email notifications, you can add the email addresses in the CC field.
  • enter a short title to the change in the summary field. Don't omit the [Qt] prefix in the beginning
  • enter a description of the change in the description field and which QtWebKit releases are applicable.
• Attach the changed qdoc file or the new qdoc file n the bug report. If your document embeds images, attach them to the bug report as well. When attaching documents, just add a short description and leave the other fields as they are.
• Wait for review comments and make a new version of the qdoc file as necessary

Having your documentation contribution cherry picked to a previous QtWebKit release

You can work with QtWebKit release manager Ademar Reis by email or over IRC to get your changes cherry picked to a QtWebKit release.

Communication

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

Appendix: Installing git and checking out the documentation sources using git

Git is a revision control system that many QtWebKit developers use to work with the WebKit SVN repository. It is not mandatory to use git or any other SVN client to contribute documentation. If you want to use git to be able to pull a local copy of the WebKit sources and documentation, here's how you can get started.

WebKit SVN repository is mirrored 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. After installing Cygwin, add the bin directory of the Cygwin installation to your system's 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.

Alternatively, you can Since the documentation is stored together with the source code, technical writes can also check out the sources and documentation. 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