qtcreator-documentation.qdoc 14.6 KB
Newer Older
1 2
/****************************************************************************
**
3
** Copyright (C) 2017 The Qt Company Ltd.
4
** Contact: https://www.qt.io/licensing/
5
**
6
** This file is part of the Qt Creator documentation.
7
**
8 9 10 11 12 13 14
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
15
**
16
** GNU Free Documentation License Usage
17 18
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
19 20 21 22
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23 24 25 26 27 28 29 30 31 32 33
**
****************************************************************************/

/*!
    \previouspage external-tool-spec.html
    \page qtcreator-documentation.html
    \nextpage coding-style.html

    \title Writing Documentation

    When you add plugins or contribute new features to \QC, you probably want
34 35 36 37
    other people to know about them and to be able to use them. Therefore, you
    should also contribute documentation for them. Follow the guidelines in this
    section to make sure that your documentation fits in well with the rest of
    the \QC documentation.
38 39 40 41 42 43 44

    When you contribute a plugin, you should write documentation both for the
    developers who use \QC and for the ones who develop it.

    Write the following user documentation for addition to the \QC Manual:

    \list
Tobias Hunger's avatar
Tobias Hunger committed
45 46
        \li  Overview topic, which describes the purpose of your plugin from the
             viewpoint of \QC users
47

Tobias Hunger's avatar
Tobias Hunger committed
48
        \li  Procedure topics, which describe how to use your plugin as part of \QC
49

Tobias Hunger's avatar
Tobias Hunger committed
50 51
        \li  Reference topics, which contain information that developers
             occasionally need to look up (optional)
52 53 54 55 56 57
    \endlist

    Write the following developer documentation for addition to the Extending
    \QC Manual:

    \list
Tobias Hunger's avatar
Tobias Hunger committed
58 59
        \li  Overview topic, which describes the architecture and use cases for
             your plugin from the viewpoint of \QC developers
60

Tobias Hunger's avatar
Tobias Hunger committed
61
        \li  API documentation, which is generated from code comments
62 63 64 65 66
    \endlist

    \section1 Configuring the Documentation Project

    \QC documentation is written by using QDoc. For more information about using
67
    QDoc, see the \l{http://doc.qt.io/qt-5/qdoc-index.html}{QDoc Manual}.
68

69 70
    QDoc finds the new topics automatically, when you place them as \c {.qdoc}
    files in the correct folder. However, to make the topics accessible to
71 72 73
    readers, you must also add them to the table of contents
    (\c {doc\src\qtcreator-toc.qdoc}) and fix the next page and previous page
    links to them from other topics.
74 75 76 77 78

    \section2 Creating Folders and Files

    These instructions apply only to the \QC Manual. Add API documentation
    directly to the code source files. However, you can write an API overview
79
    also as a separate \c {.qdoc} file.
80 81 82 83 84

    Create a subfolder for your documentation in the \QC project folder in the
    \c {doc\src} folder. Create a separate file for each topic.

    The easiest way is probably to copy an existing file, save it as a new file,
85 86 87
    and modify it. This way, you already have samples of the necessary bits and
    pieces in place, such as topic start and end commands, copyright statement,
    links to next and previous topics, and topic title.
88 89 90

    \section2 Integrating Topics to Documentation

91 92
    You must integrate your new topics to the \QC Manual and Extending \QC
    Manual by adding links to them to the table of contents and to other
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
    relevant topics.

    To link to the topic, you can use the topic title. For example:

    \code
    \l{Integrating Topics to Documentation}
    \endcode

    This does not work if topic titles are not unique. Also, if you change the
    title, the link breaks. You can avoid this risk by adding the \c {\target}
    command to your topic and then linking to the target.

    \section2 Updating Next and Previous Links

    When you add new topics to a document, you must also change the navigation
    links of the topics around them. This is very error prone when done
109
    manually, and therefore we have a script called \c {fixnavi.pl} for it. For
110 111 112 113
    the script to work, you must add the \c {\nextpage} and \c {\previouspage}
    commands to the topic, with dummy values (for example,
    \c {\nextpage=anything.html}).

114 115 116 117 118
    \note The script creates the links according to the TOC in the topic set as
    the value of the \c indexTitle configuration parameter
    (\c {doc\src\qtcreator-toc.qdoc}). If your topics are not listed in the TOC,
    the script removes the \c {\nextpage} and \c {\previouspage} commands from
    them.
119 120 121 122 123 124 125 126

    To run the script, you must have Perl installed. If you build Qt yourself,
    you should already have it. Otherwise, download and install
    \l{http://www.perl.org/}{Perl}.

    To run the script, enter the following command in the doc folder:

    \list
Tobias Hunger's avatar
Tobias Hunger committed
127
        \li  nmake fixnavi (on Windows)
128

Tobias Hunger's avatar
Tobias Hunger committed
129
        \li  make fixnavi (on Linux)
130 131 132 133 134
    \endlist

    \section1 Writing Text

    Follow the guidelines for
135
    \l{http://wiki.qt.io/Writing_Qt_Documentation}{writing Qt documentation}.
136 137 138

    The documentation must be grammatically correct English and use the standard
    form of written language. Do not use dialect or slang words. Use idiomatic
139 140
    language, that is, expressions that are characteristic for English. If
    possible, ask a native English speaker for a review.
141 142 143 144 145 146 147 148 149 150 151 152

    \section2 Capitalizing Headings

    Use the book title capitalization style for all titles and section headings
    (\c {\title}, \c {\section1}, \c {\section2}, and so on). For more
    information, see \l{Using Book Style Capitalization}.

    \section1 Using Images

    You can illustrate your documentation by using screen shots, diagrams, and
    other images.

153 154 155 156 157 158 159
    Use the \c {\image} and \c {\inlineimage} QDoc commands to refer to images
    from the text. You do not need to add paths to image names. For example:

    \code
    \image riot.png
    \endcode

Leena Miettinen's avatar
Leena Miettinen committed
160 161
    \section2 Taking Screen Shots

162
    \QC has the native look and feel on Windows, Linux, and \macos, and therefore,
163 164 165 166
    screen shots can end up looking very different, depending on who takes them
    and which system they use. To try to preserve a consistent look and feel in
    the \QC Manual, observe the guidelines listed in this section when taking
    screen shots.
Leena Miettinen's avatar
Leena Miettinen committed
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197

    To make the images look similar regardless of the operating system they were
    taken on, you are asked to adjust their size to 75%. This makes the screen
    shots hard to read, but they are provided more as reassurance for users that
    they are in the correct place in the UI than as an actual source of
    information. To make sure that no important information is lost, always
    place example values also in the text.

    \list
        \li Use the screen resolution of 1024x768 (this is available on all
            screens).

        \li Use the aspect ratio of 4:3.

        \li Open the application in the maximum size on full screen.

        \li Use your favorite tool to take the screen shot.

        \li Include only the part of the screen that you need (you can crop the
            image also in the screen capture tool).

        \li In the screen capture tool, open the screen shot and adjust its size
            to 75%.

        \li To highlight parts of the screen shot, use the images of numbers
            that are stored in \c{doc\images\numbers} in the \QC repository.

        \li Before you submit the images to the repository, optimize them to
            save space.
    \endlist

198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
    \section2 Hightlighting Parts of the Screen

    You can use number icons in screenshots to highlight parts of the screenshot
    (instead of using red arrows or borders, or something similar). You can then
    refer to the numbers in text. For and example, see the
    \l{http://doc.qt.io/qt-5/topics-app-development.html}{Development Tools}
    topic in the Qt reference documentation.

    This improves the consistency of the look and feel of Qt documentation,
    and eliminates the need to describe parts of the UI in the text, because
    you can just insert the number of the element you are referring to in
    brackets.

    You can find a set of images that show the numbers from 1 to 10  in the
    \c doc\images\numbers directory (or in the \c qtdoc module sources in
    \c doc\images\numbers).

    To use the numbers:

    \list
        \li Take a screenshot as described above.
        \li After resizing the screenshot, copy-paste the number images on
            the screenshot to the places that you want to refer to from text.
    \endlist

Leena Miettinen's avatar
Leena Miettinen committed
223 224
    \section2 Optimizing Images

225 226 227 228 229
    Save images in the PNG format in the \QC project folder in the
    \c {doc\images} folder. Binary images can easily add megabytes to the Git
    history. To keep the history as small as possible, the Git post-commit hooks
    remind you to try to keep image size below 50 kilobytes. To achieve this
    goal, crop images so that only relevant information is visible in them.
Leena Miettinen's avatar
Leena Miettinen committed
230 231 232
    Before committing images, optimize them by using an image optimization tool.

    Optimization should not visibly reduce image quality. If it does, do not do
233 234 235
    it.

    You can use a web service, such as \l{https://tinypng.com}, or an image
236 237
    optimization tool to shrink the images. For example, you can use the Radical
    Image Optimization Tool (RIOT) on Windows (very efficient) or ImageOptim on
238
    \macos (much less efficient), or some other tool available on Linux.
Leena Miettinen's avatar
Leena Miettinen committed
239 240 241 242 243

    With ImageOptim, you simply drag and drop the image files to the
    application. The following section describes the settings to use for RIOT.

    \section3 Using RIOT
244 245 246 247 248 249 250 251

    Download and install \l{http://luci.criosweb.ro/riot/}{RIOT}.

    \image riot.png

    Open your images in RIOT and use the following settings for them:

    \list
Tobias Hunger's avatar
Tobias Hunger committed
252
        \li  Color reduction: Optimal 256 colors palette
253

Tobias Hunger's avatar
Tobias Hunger committed
254
        \li  Reduce colors to: 256
255

Tobias Hunger's avatar
Tobias Hunger committed
256
        \li  Best compression (slow)
257

Tobias Hunger's avatar
Tobias Hunger committed
258
        \li  Color quantization algorithm: NeuQuant neural-net (slow)
259

Tobias Hunger's avatar
Tobias Hunger committed
260
        \li  External optimizers: OptiPNG o3
261 262 263
    \endlist

    Compare the initial and optimized images to check that image quality is
Leena Miettinen's avatar
Leena Miettinen committed
264
    preserved. If the image quality deteriorates, do not use color reduction
265
    (select the \uicontrol {True Color} option, instead).
Leena Miettinen's avatar
Leena Miettinen committed
266 267

    You can also see the sizes of the initial and optimized image.
268

269 270 271 272 273 274 275 276 277 278 279 280
    \section3 Using OptiPNG

    Download and install \l{https://sourceforge.net/projects/optipng/}{OptiPNG}.

    OptiPNG is a command-line tool that you can invoke from the \QC project
    folder (or any folder that contains your project). To optimize a screenshot,
    enter the following command (here, from the \QC project folder):

    \code
    optipng -o 7 -strip all doc/images/<screenshot_name>
    \endcode

281 282 283 284 285 286 287
    \section1 Building Documentation

    You use QDoc to build the documentation. Build the documentation from time
    to time, to check its structure and the validity of the QDoc commands.
    The error messages that QDoc issues are generally very useful for
    troubleshooting.

288 289 290 291 292
    For more information about setting up the build environment if you do not
    want to build the whole Qt, see
    \l{https://wiki.qt.io/Building_Qt_Documentation}{Building Qt Documentation}
    on the Qt wiki.

293
    The content and formatting of documentation are separated in QDoc.
294
    The documentation configuration, style sheets, and templates have
295 296 297
    changed over time, so they differ between Qt and \QC versions. Since \QC
    version 3.3, only Qt 5 is supported for building documentation. The
    templates to use are defined by the
298
    \c {qt5\qtbase\doc\global\qt-html-templates-offline.qdocconf} and
299 300 301
    \c {qt5\qtbase\doc\global\qt-html-templates-online.qdocconf} configuration
    file. They are fetched from Qt sources by adding the following lines to the
    qdocconf file:
302

303 304 305
    \list
        \li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)}
            for help files
306 307
        \li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)}
            for publishing on the web
308
    \endlist
309

310 311 312
    \note To have the correct fonts loaded for the online version, you must be
    running it on a web server.

313
    \note If the styles look wrong to you when reading help files in \QC or \QA,
314 315
    you might be looking at them in the QTextBrowser instead of the Qr WebEngine
    browser. This happens if you do not have Qt WebEngine installed.
316 317 318 319

    To build documentation for the sources from the qtcreator master branch, use
    build scripts defined in the doc.pri file. To build all \QC docs in the
    help format and to create help files (.qch), enter the following build
320
    commands from the project folder (after running qmake):
321 322

    \list
Tobias Hunger's avatar
Tobias Hunger committed
323
        \li  nmake docs (on Windows)
324

325
        \li  make docs (on Linux and \macos)
326 327
    \endlist

328
    The \QC Manual HTML files are generated in the \c {doc/qtcreator} directory.
329
    The Extending \QC Manual files are generated in the
330
    \c {doc/qtcreator-dev} directory. The help files (\c {.qch}) are generated in the
331 332
    \c {share/doc/qtcreator} directory in the \QC build directory on Windows and
    Linux, and in the \c {bin/Qt Creator.app/Contents/Resources/app} directory
333
    on \macos. You can view the HTML files in a browser and the help files in
334 335
    the \QC \uicontrol Help mode. For more information about adding the help
    files to \QC, see
Sergio Ahumada's avatar
Sergio Ahumada committed
336
    \l{http://doc.qt.io/qtcreator/creator-help.html#adding-external-documentation}
337 338
    {Adding External Documentation}.

339
    Besides \c docs, you have the following options:
340 341

    \list
Tobias Hunger's avatar
Tobias Hunger committed
342 343
        \li  html_docs - build \QC Manual in help format, but do not generate a
             help file
344

Tobias Hunger's avatar
Tobias Hunger committed
345 346
        \li  dev_html_docs - build Extending \QC Manual in help format, but do
             not generate a help file
347

Tobias Hunger's avatar
Tobias Hunger committed
348 349
        \li  qch_docs - build \QC Manual in help format and generate a help file
             (.qch)
350

Tobias Hunger's avatar
Tobias Hunger committed
351 352
        \li  dev_qch_docs - build Extending \QC Manual in help format and
             generate a help file (.qch)
353

Tobias Hunger's avatar
Tobias Hunger committed
354 355
        \li  docs_online - build \QC Manual and Extending \QC Manual in online
             format
356

Tobias Hunger's avatar
Tobias Hunger committed
357
        \li  html_docs_online - build \QC Manual in online format
358

Tobias Hunger's avatar
Tobias Hunger committed
359
        \li  dev_html_docs_online - build Extending \QC Manual in online format
360 361 362
    \endlist

*/