Changes between Version 13 and Version 14 of QtWebKitDocContrib


Ignore:
Timestamp:
Oct 5, 2010 6:37:53 AM (10 years ago)
Author:
Henry Haverinen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • QtWebKitDocContrib

    v13 v14  
    22= Contributing documentation to QtWebKit =
    33
    4 UNDER CONSTRUCTION! This wiki page contains the information that is relevant for technical writers contributing documentation to QtWebKit.
     4UNDER 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.
    55
    66QtWebKit currently comes with a lot of documentation for C++ developers, and we'd like to extend the documentation also for web developers.
     
    1616On 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.
    1717
    18 == Installing git ==
     18== Getting access to the existing documentation source files ==
    1919
    20 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].
     20The simplest way to get the existing documentation files is to use the web interface of WebKit Trac at  http://trac.webkit.org/browser/trunk/WebKit/qt/docs. That URL points to the WebKit/qt/docs directory where all the Qt specific documentation articles are stored. The C++ API documentation is included in line in the C++ source files.
    2121
    22 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
     22== Building the documentation articles  ==
     23
     24TBD: this will require some additional tools: To build the complete 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.
     25
     26TBD: should writers just use qdoc directly to build the articles?
     27
     28== Submitting a documentation contribution ==
     29
     30Documentation 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).
     31
     32 * Make your changes. Typically, you would change  existing qdoc files or create new qdoc files.
     33 * Create a bug in the WebKit bugzilla. Use this template as the starting point: http://webkit.org/new-qtwebkit-bug.
     34   * Leave the component as "New bugs".
     35   * Use the severity "Enhancement" if your patch is an improvement and not related to a bug in documentation.
     36   * Select 528+ (Nightly build) as the version
     37   * Enter "ademar.reis@openbossa.org" as the assignee
     38   * enter a short title to the change in the summary field. Don't omit the [Qt] in the beginning
     39   * enter a description of the change in the description field
     40 * Attach the changed qdoc file or the new qdoc file n the bug report
     41 * Wait for Ademar to prepare a change log and a patch
     42 * Wait for review comments and make a new version of the qdoc file as necessary
     43
     44== Having your documentation contribution cherry picked to a previous QtWebKit release ==
     45
     46You can work with QtWebKit release manager Ademar Reis to get your changes cherry picked to a QtWebKit release.
     47
     48== Communication ==
     49
     50We 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.
     51
     52
     53== Appendix: Installing git and checking out the documentation sources using git ==
     54
     55Git 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.
     56
     57WebKit SVN repository is mirrored 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://git-scm.com/download
    2358
    2459 * 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.
     
    2661After 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.
    2762
    28 == Checking out the sources ==
    2963
    30 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:
     64Alternatively, 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:
    3165
    3266{{{
     
    4579And to switch to a branch simply use {{{git checkout branchname}}}
    4680
    47 === Where to find the documentation ===
    4881
    49 The C++ API documentation is included in line in the C++ source files. Standalone documentation articles are in the WebKit/qt/docs directory.
    50 
    51 == TODO: installing other tools ==
    52 
    53 TODO: what other tools are needed to build the documentation?
    54 
    55 == Building the documentation articles  ==
    56 
    57 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.
    58 
    59 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.
    60 
    61 == Submitting a documentation contribution ==
    62 
    63 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).
    64 
    65 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.
    66 
    67  * Make your changes in the webkit source code directory. Typically, you would change  existing qdoc files or create new qdoc files.
    68  * Run the {{{WebKitTools/Scripts/prepare-ChangeLog}}} script to create an entry for your changes in each relevant ChangeLog file.
    69  * Edit the ChangeLog files reported by the prepare-ChangeLog script:
    70    * 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.
    71    * Add a short description and paste the bug URL below it. Add an extra line and a detailed description if necessary.
    72    * Precede the short description with "[Qt]" since your documentation patch is specific to the Qt port of WebKit.
    73    * The description text should be the same in all ChangeLog files.
    74    * 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.
    75  * 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)
    76  * Attach the patch to the bug report, set the {{{review}}} flag to '?' and the {{{commit-queue}}} flag to '?'
    77  * Wait :)
    78 
    79 == Having your documentation contribution cherry picked to a previous QtWebKit release ==
    80 
    81 TBD
    82 
    83 == Communication ==
    84 
    85 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.