forked from qt-creator/qt-creator
d59d8b568d
Change-Id: I77f1cbbfc17d759d1587caf2a25a53498848e2ca Reviewed-by: Jake Petroules <jake.petroules@petroules.com> Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
320 lines
12 KiB
Plaintext
320 lines
12 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
|
|
** Contact: http://www.qt-project.org/legal
|
|
**
|
|
** This file is part of Qt Creator
|
|
**
|
|
**
|
|
** GNU Free Documentation License
|
|
**
|
|
** Alternatively, this file may be used under the terms of the GNU Free
|
|
** Documentation License version 1.3 as published by the Free Software
|
|
** Foundation and appearing in the file included in the packaging of this
|
|
** file.
|
|
**
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\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
|
|
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.
|
|
|
|
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
|
|
|
|
\li Overview topic, which describes the purpose of your plugin from the
|
|
viewpoint of \QC users
|
|
|
|
\li Procedure topics, which describe how to use your plugin as part of \QC
|
|
|
|
\li Reference topics, which contain information that developers
|
|
occasionally need to look up (optional)
|
|
|
|
\endlist
|
|
|
|
Write the following developer documentation for addition to the Extending
|
|
\QC Manual:
|
|
|
|
\list
|
|
|
|
\li Overview topic, which describes the architecture and use cases for
|
|
your plugin from the viewpoint of \QC developers
|
|
|
|
\li API documentation, which is generated from code comments
|
|
|
|
\endlist
|
|
|
|
\section1 Configuring the Documentation Project
|
|
|
|
\QC documentation is written by using QDoc. For more information about using
|
|
QDoc, see the \l{http://qt-project.org/doc/qt-5.1/qdoc/qdoc-index.html}
|
|
{QDoc Manual}.
|
|
|
|
QDoc finds the new topics automatically, when you place them as .qdoc files
|
|
in the correct folder. However, to make the topics accessible to readers,
|
|
you must also add them to the table of contents and fix the next page and
|
|
previous page links to them from other topics.
|
|
|
|
\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
|
|
also as a separate .qdoc file.
|
|
|
|
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,
|
|
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.
|
|
|
|
\section2 Integrating Topics to Documentation
|
|
|
|
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
|
|
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
|
|
manually, and therefore we have a script called \c fixnavi.pl for it. For
|
|
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}).
|
|
|
|
\note The script creates the links according to the TOC on the front page.
|
|
If your topics are not listed in the TOC, the script removes the
|
|
\c {\nextpage} and \c {\previouspage} commands from them.
|
|
|
|
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
|
|
|
|
\li nmake fixnavi (on Windows)
|
|
|
|
\li make fixnavi (on Linux)
|
|
|
|
\endlist
|
|
|
|
\section1 Writing Text
|
|
|
|
Follow the guidelines for
|
|
\l{http://qt-project.org/wiki/Writing_Qt_Documentation}
|
|
{writing Qt documentation}.
|
|
|
|
The documentation must be grammatically correct English and use the standard
|
|
form of written language. Do not use dialect or slang words. Use idiomatic
|
|
language, that is, expressions that are characteristic for English.
|
|
If possible, ask a native English speaker for a review.
|
|
|
|
\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.
|
|
|
|
\section2 Taking Screen Shots
|
|
|
|
\QC has the native look and feel on Windows, Linux, and OS X, and
|
|
therefore, 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.
|
|
|
|
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
|
|
|
|
\section2 Optimizing Images
|
|
|
|
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.
|
|
Before committing images, optimize them by using an image optimization tool.
|
|
|
|
Optimization should not visibly reduce image quality. If it does, do not do
|
|
it. You can use the Radical Image Optimization Tool (RIOT) on Windows (very
|
|
efficient) or ImageOptim on OS X (much less efficient), or some other tool
|
|
available on Linux.
|
|
|
|
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
|
|
|
|
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
|
|
|
|
\section2 Optimizing Images
|
|
|
|
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
|
|
|
|
\li Color reduction: Optimal 256 colors palette
|
|
|
|
\li Reduce colors to: 256
|
|
|
|
\li Best compression (slow)
|
|
|
|
\li Color quantization algorithm: NeuQuant neural-net (slow)
|
|
|
|
\li External optimizers: OptiPNG o3
|
|
|
|
\endlist
|
|
|
|
Compare the initial and optimized images to check that image quality is
|
|
preserved. If the image quality deteriorates, do not use color reduction
|
|
(select the \gui {True Color} option, instead).
|
|
|
|
You can also see the sizes of the initial and optimized image.
|
|
|
|
\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.
|
|
|
|
The content and formatting of documentation are separated in QDoc.
|
|
The documentation configuration, style sheets, and templates have
|
|
changed over time, so they differ between Qt and \QC versions. In Qt 4,
|
|
separate style sheets are used to generate help files for \QC and online
|
|
documentation for the Web.
|
|
|
|
In Qt 5, only one set of templates is used, as defined by the
|
|
\c {qt5\qtbase\doc\global\qt-module-defaults.qdocconf} configuration file.
|
|
It is fetched from Qt sources by adding the following line to the qdocconf
|
|
file:
|
|
|
|
\c {include ($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)}
|
|
|
|
To pick the Qt to use, run qmake from either Qt 4 or Qt 5.
|
|
|
|
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
|
|
commands from the project folder (after running qmake):
|
|
|
|
\list
|
|
|
|
\li nmake docs (on Windows)
|
|
\li make docs (on Linux and OS X)
|
|
|
|
\endlist
|
|
|
|
The \QC Manual HTML files are generated in the \c {doc/html} directory.
|
|
The Extending \QC Manual files are generated in the
|
|
\c {doc/html-dev} directory. The help files (.qch) are generated in the
|
|
\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
|
|
on OS X. You can view the HTML files in a browser and the help files in
|
|
the \QC \gui Help mode. For more information about adding the help files to
|
|
\QC, see
|
|
\l{http://qt-project.org/doc/qtcreator-2.8/creator-help.html#adding-external-documentation}
|
|
{Adding External Documentation}.
|
|
|
|
Besides \c docs, you have the following options:
|
|
|
|
\list
|
|
|
|
\li html_docs - build \QC Manual in help format, but do not generate a
|
|
help file
|
|
|
|
\li dev_html_docs - build Extending \QC Manual in help format, but do
|
|
not generate a help file
|
|
|
|
\li qch_docs - build \QC Manual in help format and generate a help file
|
|
(.qch)
|
|
|
|
\li dev_qch_docs - build Extending \QC Manual in help format and
|
|
generate a help file (.qch)
|
|
|
|
\li docs_online - build \QC Manual and Extending \QC Manual in online
|
|
format
|
|
|
|
\li html_docs_online - build \QC Manual in online format
|
|
|
|
\li dev_html_docs_online - build Extending \QC Manual in online format
|
|
|
|
\endlist
|
|
|
|
*/
|