feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Polish qtcreator-documentation.qdoc

Browse Source 
Add a couple of \c's in places and reformat the text where
necessary.

Change-Id: Ib4083af1e9deadcc1c12e94f6ccb77c0432d7ff5
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>
This commit is contained in:
Tobias Hunger
2015-06-23 16:59:42 +02:00
parent 79251408ea
commit 7b401a1557
1 changed files with 31 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
doc/api/qtcreator-documentation.qdoc
View File

@@ -24,10 +24,10 @@
\title Writing Documentation \title Writing Documentation
When you add plugins or contribute new features to \QC, you probably want 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, other people to know about them and to be able to use them. Therefore, you
you should also contribute documentation for them. Follow the guidelines in should also contribute documentation for them. Follow the guidelines in this
this section to make sure that your documentation fits in well with the rest section to make sure that your documentation fits in well with the rest of
of the \QC documentation. the \QC documentation.
When you contribute a plugin, you should write documentation both for the When you contribute a plugin, you should write documentation both for the
developers who use \QC and for the ones who develop it. developers who use \QC and for the ones who develop it.
@@ -35,7 +35,6 @@
Write the following user documentation for addition to the \QC Manual: Write the following user documentation for addition to the \QC Manual:
\list \list
\li Overview topic, which describes the purpose of your plugin from the \li Overview topic, which describes the purpose of your plugin from the
viewpoint of \QC users viewpoint of \QC users
@@ -43,58 +42,52 @@
\li Reference topics, which contain information that developers \li Reference topics, which contain information that developers
occasionally need to look up (optional) occasionally need to look up (optional)
\endlist \endlist
Write the following developer documentation for addition to the Extending Write the following developer documentation for addition to the Extending
\QC Manual: \QC Manual:
\list \list
\li Overview topic, which describes the architecture and use cases for \li Overview topic, which describes the architecture and use cases for
your plugin from the viewpoint of \QC developers your plugin from the viewpoint of \QC developers
\li API documentation, which is generated from code comments \li API documentation, which is generated from code comments
\endlist \endlist
\section1 Configuring the Documentation Project \section1 Configuring the Documentation Project
\QC documentation is written by using QDoc. For more information about using \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, see the \l{http://doc.qt.io/qt-5/qdoc-index.html}{QDoc Manual}.
{QDoc Manual}.
QDoc finds the new topics automatically, when you place them as .qdoc files QDoc finds the new topics automatically, when you place them as \c {.qdoc}
in the correct folder. However, to make the topics accessible to readers, files in the correct folder. However, to make the topics accessible to
you must also add them to the table of contents and fix the next page and readers, you must also add them to the table of contents and fix the next
previous page links to them from other topics. page and previous page links to them from other topics.
\section2 Creating Folders and Files \section2 Creating Folders and Files
These instructions apply only to the \QC Manual. Add API documentation These instructions apply only to the \QC Manual. Add API documentation
directly to the code source files. However, you can write an API overview directly to the code source files. However, you can write an API overview
also as a separate .qdoc file. also as a separate \c {.qdoc} file.
Create a subfolder for your documentation in the \QC project folder in the Create a subfolder for your documentation in the \QC project folder in the
\c {doc\src} folder. Create a separate file for each topic. \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, 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 modify it. This way, you already have samples of the necessary bits and
and pieces in place, such as topic start and end commands, copyright pieces in place, such as topic start and end commands, copyright statement,
statement, links to next and previous topics, and topic title. links to next and previous topics, and topic title.
\section2 Integrating Topics to Documentation \section2 Integrating Topics to Documentation
You must integrate your new topics to the \QC Manual and Extending You must integrate your new topics to the \QC Manual and Extending \QC
\QC Manual by adding links to them to the table of contents and to other Manual by adding links to them to the table of contents and to other
relevant topics. relevant topics.
To link to the topic, you can use the topic title. For example: To link to the topic, you can use the topic title. For example:
\code \code
\l{Integrating Topics to Documentation} \l{Integrating Topics to Documentation}
\endcode \endcode
This does not work if topic titles are not unique. Also, if you change the This does not work if topic titles are not unique. Also, if you change the
@@ -105,7 +98,7 @@
When you add new topics to a document, you must also change the navigation 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 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 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} the script to work, you must add the \c {\nextpage} and \c {\previouspage}
commands to the topic, with dummy values (for example, commands to the topic, with dummy values (for example,
\c {\nextpage=anything.html}). \c {\nextpage=anything.html}).
@@ -121,23 +114,20 @@
To run the script, enter the following command in the doc folder: To run the script, enter the following command in the doc folder:
\list \list
\li nmake fixnavi (on Windows) \li nmake fixnavi (on Windows)
\li make fixnavi (on Linux) \li make fixnavi (on Linux)
\endlist \endlist
\section1 Writing Text \section1 Writing Text
Follow the guidelines for Follow the guidelines for
\l{http://wiki.qt.io/Writing_Qt_Documentation} \l{http://wiki.qt.io/Writing_Qt_Documentation}{writing Qt documentation}.
{writing Qt documentation}.
The documentation must be grammatically correct English and use the standard The documentation must be grammatically correct English and use the standard
form of written language. Do not use dialect or slang words. Use idiomatic form of written language. Do not use dialect or slang words. Use idiomatic
language, that is, expressions that are characteristic for English. language, that is, expressions that are characteristic for English. If
If possible, ask a native English speaker for a review. possible, ask a native English speaker for a review.
\section2 Capitalizing Headings \section2 Capitalizing Headings
@@ -159,11 +149,11 @@
\section2 Taking Screen Shots \section2 Taking Screen Shots
\QC has the native look and feel on Windows, Linux, and OS X, and \QC has the native look and feel on Windows, Linux, and OS X, and therefore,
therefore, screen shots can end up looking very different, depending on who screen shots can end up looking very different, depending on who takes them
takes them and which system they use. To try to preserve a consistent look and which system they use. To try to preserve a consistent look and feel in
and feel in the \QC Manual, observe the guidelines listed in this section the \QC Manual, observe the guidelines listed in this section when taking
when taking screen shots. screen shots.
To make the images look similar regardless of the operating system they were 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 taken on, you are asked to adjust their size to 75%. This makes the screen
@@ -173,7 +163,6 @@
place example values also in the text. place example values also in the text.
\list \list
\li Use the screen resolution of 1024x768 (this is available on all \li Use the screen resolution of 1024x768 (this is available on all
screens). screens).
@@ -194,7 +183,6 @@
\li Before you submit the images to the repository, optimize them to \li Before you submit the images to the repository, optimize them to
save space. save space.
\endlist \endlist
\section2 Optimizing Images \section2 Optimizing Images
@@ -210,10 +198,9 @@
it. it.
You can use a web service, such as \l{https://tinypng.com}, or an image You can use a web service, such as \l{https://tinypng.com}, or an image
optimization tool to shrink the images. For example, you optimization tool to shrink the images. For example, you can use the Radical
can use the Radical Image Optimization Tool (RIOT) on Windows (very Image Optimization Tool (RIOT) on Windows (very efficient) or ImageOptim on
efficient) or ImageOptim on OS X (much less efficient), or some other tool OS X (much less efficient), or some other tool available on Linux.
available on Linux.
With ImageOptim, you simply drag and drop the image files to the With ImageOptim, you simply drag and drop the image files to the
application. The following section describes the settings to use for RIOT. application. The following section describes the settings to use for RIOT.
@@ -227,7 +214,6 @@
Open your images in RIOT and use the following settings for them: Open your images in RIOT and use the following settings for them:
\list \list
\li Color reduction: Optimal 256 colors palette \li Color reduction: Optimal 256 colors palette
\li Reduce colors to: 256 \li Reduce colors to: 256
@@ -237,7 +223,6 @@
\li Color quantization algorithm: NeuQuant neural-net (slow) \li Color quantization algorithm: NeuQuant neural-net (slow)
\li External optimizers: OptiPNG o3 \li External optimizers: OptiPNG o3
\endlist \endlist
Compare the initial and optimized images to check that image quality is Compare the initial and optimized images to check that image quality is
@@ -264,7 +249,6 @@
qdocconf file: qdocconf file:
\list \list
\li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)} \li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)}
for help files for help files
\li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)} \li \c {include ($QT_INSTALL_DOCS/global/qt-html-templates-online.qdocconf)}
@@ -285,27 +269,25 @@
commands from the project folder (after running qmake): commands from the project folder (after running qmake):
\list \list
\li nmake docs (on Windows) \li nmake docs (on Windows)
\li make docs (on Linux and OS X)
\li make docs (on Linux and OS X)
\endlist \endlist
The \QC Manual HTML files are generated in the \c {doc/html} directory. The \QC Manual HTML files are generated in the \c {doc/html} directory.
The Extending \QC Manual files are generated in the The Extending \QC Manual files are generated in the
\c {doc/html-dev} directory. The help files (.qch) are generated in the \c {doc/html-dev} directory. The help files (\c {.qch}) are generated in the
\c {share/doc/qtcreator} directory in the \QC build directory on Windows and \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 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 on OS X. 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 the \QC \uicontrol Help mode. For more information about adding the help
\QC, see files to \QC, see
\l{http://doc.qt.io/qtcreator/creator-help.html#adding-external-documentation} \l{http://doc.qt.io/qtcreator/creator-help.html#adding-external-documentation}
{Adding External Documentation}. {Adding External Documentation}.
Besides \c docs, you have the following options: Besides \c docs, you have the following options:
\list \list
\li html_docs - build \QC Manual in help format, but do not generate a \li html_docs - build \QC Manual in help format, but do not generate a
help file help file
@@ -324,7 +306,6 @@
\li html_docs_online - build \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 \li dev_html_docs_online - build Extending \QC Manual in online format
\endlist \endlist
*/ */