2 | | http://qt.gitorious.org/qt/pages/DocManual |
| 2 | = Contributing documentation to QtWebKit = |
| 3 | |
| 4 | UNDER CONSTRUCTION! This wiki page contains the information that is relevant for technical writers contributing documentation to QtWebKit. |
| 5 | |
| 6 | QtWebKit comes with extensive documentation for C++ developers, and we'd like to extend the documentation also for web developers. |
| 7 | |
| 8 | 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. |
| 9 | |
| 10 | The C++ API documentation is included in line in the C++ source files. Standalone documentation articles are in the WebKit/qt/docs directory. |
| 11 | |
| 12 | 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. |
| 13 | |
| 14 | == Checking out the sources == |
| 15 | |
| 16 | Since the documentation is stored together with the source code, also technical writes need to check out the sources. In this wiki, we describe how to do this using the [http://gitorious.org/qtwebkit public git repository] |
| 17 | hosted at [http://gitorious.org/qtwebkit Gitorious.org]. This is a mirror of the WebKit SVN repository. |
| 18 | |
| 19 | {{{ |
| 20 | git clone git://gitorious.org/webkit/webkit.git |
| 21 | }}} |
| 22 | |
| 23 | To see the remote branches you just fetched do: |
| 24 | {{{ |
| 25 | git branch -r |
| 26 | }}} |
| 27 | |
| 28 | For the tags simply do: |
| 29 | {{{ |
| 30 | git tag |
| 31 | }}} |
| 32 | |
| 33 | And to switch to a branch or a tag simply use {{{git checkout}}} |
| 34 | |
| 35 | == Submitting a documentation contribution == |
| 36 | |
| 37 | 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. |
| 38 | * Make your changes in the webkit source code directory. Typically, you would change existing qdoc files or create new qdoc files. |
| 39 | * Run the {{{WebKitTools/Scripts/prepare-ChangeLog}}} script to create an entry for your changes in each relevant ChangeLog file. |
| 40 | * Edit the ChangeLog files reported by the prepare-ChangeLog script: |
| 41 | * 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. |
| 42 | * Add a short description and paste the bug URL below it. Add an extra line and a detailed description if necessary. |
| 43 | * Precede the short description with "[Qt]" since your documentation patch is specific to the Qt port of WebKit. |
| 44 | * The description text should be the same in all ChangeLog files. |
| 45 | * 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. |
| 46 | * 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) |
| 47 | * Attach the patch to the bug report, set the {{{review}}} flag to '?' and the {{{commit-queue}}} flag to '?' |
| 48 | * Wait :) |
| 49 | |
| 50 | == Building the documentation articles == |
| 51 | |
| 52 | 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. |
| 53 | |
| 54 | 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. |
| 55 | |
| 56 | == Communication == |
| 57 | |
| 58 | 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. |