1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
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
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
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
/****************************************************************************
**
** Copyright (c) 2013 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.
**
**
****************************************************************************/
/*!
\contentspage{index.html}{Qt Creator}
\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
\o Overview topic, which describes the purpose of your plugin from the
viewpoint of \QC users
\o Procedure topics, which describe how to use your plugin as part of
\QC
\o 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
\o Overview topic, which describes the architecture and use cases for
your plugin from the viewpoint of \QC developers
\o 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 \l{http://qt-project.org/doc/qdoc/}{QDoc Reference Documentation}.
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
\o nmake fixnavi (on Windows)
\o 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.
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 the Radical Image
Optimization Tool (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
\o Color reduction: Optimal 256 colors palette
\o Reduce colors to: 256
\o Best compression (slow)
\o Color quantization algorithm: NeuQuant neural-net (slow)
\o 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.
Separate style sheets are used to generate help files for \QC and online
documentation for the Web.
The documentation configuration, style sheets, and build process have
changed over time, so they differ between Qt and \QC versions. To use the
online style, use QDoc from Qt 4.7.4 to build the docs. To use the \QC help
style, use QDoc from Qt 4.8, or later.
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:
\list
\o nmake docs (on Windows)
\o make docs (on Linux)
\endlist
The following options generate HTML that uses the help style, and therefore
require QDoc from Qt 4.8 or later:
\list
\o html_docs - build \QC Manual in help format, but do not generate a
help file
\o dev_html_docs - build Extending \QC Manual in help format, but do
not generate a help file
\o qch_docs - build \QC Manual in help format and generate a help file
(.qch)
\o dev_qch_docs - build Extending \QC Manual in help format and
generate a help file (.qch)
\endlist
The following options generate HTML that uses the online style (they do not
generate a help file), and therefore require QDoc from Qt 4.7.4:
\list
\o docs_online - build \QC Manual and Extending \QC Manual in online
format
\o html_docs_online - build \QC Manual in online format
\o dev_html_docs_online - build Extending \QC Manual in online format
\endlist
*/
|
