= Contributing documentation to QtWebKit = UNDER CONSTRUCTION! This wiki page contains the information that is relevant for technical writers contributing documentation to QtWebKit. QtWebKit comes with extensive 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 qdoc tool == The qdoc markup is a simple wiki-like format. The qdoc 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 the bin directory to the PATH. 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 [http://gitorious.org/webkit 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://help.github.com/git-installation-redirect After installing git, you can verify your installation by typing {{{git}}} on the command line, to 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}}} == 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 [http://webkit.org/coding/contributing.html 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 == 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. == Communication == We can use the QtWebKit [http://lists.webkit.org/mailman/listinfo.cgi/webkit-qt webkit-qt Mailing List] and the #qtwebkit IRC channel on freenode.net to discuss documentation, too.