feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity
Files
1fcd494cc7614bf885a78a88ef9a73aa787f00f5
qt-creator/doc/api/qtcreator-documentation.qdoc
Leena Miettinen eb74f5b71e Doc: Add information about using the number icons and OptiPNG 
...to the Extending Qt Creator Manual

Change-Id: I85dea1d815037af8334aed09c7b4ad8611d4170c
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
Reviewed-by: Tarja Sundqvist <tarja.sundqvist@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
2017-08-23 13:45:35 +00:00

363 lines
15 KiB
Plaintext
Raw Blame History

/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** 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.
**
** GNU Free Documentation License Usage
** 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. 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.
**
****************************************************************************/
/*!
\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://doc.qt.io/qt-5/qdoc-index.html}{QDoc Manual}.
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
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.
\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 \c {.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 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.
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://wiki.qt.io/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.
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 Taking Screen Shots
\QC has the native look and feel on Windows, Linux, and \macos, 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 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
\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 a web service, such as \l{https://tinypng.com}, or an image
optimization tool to shrink the images. For example, you can use the Radical
Image Optimization Tool (RIOT) on Windows (very efficient) or ImageOptim on
\macos (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
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 \uicontrol {True Color} option, instead).
You can also see the sizes of the initial and optimized image.
\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
\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.
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.
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. Since \QC
version 3.3, only Qt 5 is supported for building documentation. The
templates to use are defined by the
\c {qt5\qtbase\doc\global\qt-html-templates-offline.qdocconf} and
\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:
\list
\li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)}
for help files
\li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)}
for publishing on the web
\endlist
\note To have the correct fonts loaded for the online version, you must be
running it on a web server.
\note If the styles look wrong to you when reading help files in \QC or \QA,
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.
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 \macos)
\endlist
The \QC Manual HTML files are generated in the \c {doc/qtcreator} directory.
The Extending \QC Manual files are generated in the
\c {doc/qtcreator-dev} directory. The help files (\c {.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 \macos. You can view the HTML files in a browser and the help files in
the \QC \uicontrol Help mode. For more information about adding the help
files to \QC, see
\l{http://doc.qt.io/qtcreator/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
*/
View Git Blame Copy Permalink