diff options
Diffstat (limited to 'doc/qtcreatordev')
| -rw-r--r-- | doc/qtcreatordev/src/qtcreator-documentation.qdoc | 221 |
1 files changed, 177 insertions, 44 deletions
diff --git a/doc/qtcreatordev/src/qtcreator-documentation.qdoc b/doc/qtcreatordev/src/qtcreator-documentation.qdoc index 09d17bf0f3..c0be954940 100644 --- a/doc/qtcreatordev/src/qtcreator-documentation.qdoc +++ b/doc/qtcreatordev/src/qtcreator-documentation.qdoc @@ -473,7 +473,7 @@ \section2 Setting Up Documentation Builds - You can run \c qmake from an installed Qt to build documentation. + You can configure documentation builds using CMake or qmake. \note Since \QC version 4.12, only Qt 5.14.0 or later is supported for building documentation. @@ -500,67 +500,145 @@ 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 Qt WebEngine - browser. This happens if you do not have Qt WebEngine installed. + you might be using the QTextBrowser as the help engine backend instead of + litehtml. For more information, see + \l {https://doc.qt.io/qtcreator/creator-help.html#selecting-the-help-viewer-backend} + {Selecting the Help Viewer Backend}. - \section2 Documentation Build Commands + To build documentation for the sources from the \c qtcreator master branch, + use build scripts defined in the doc.pri file. You can build the docs + using either the offline or online style. The offline style is used for + generating HTML files included in help files (.qch), whereas the online + style is used at \l{https://doc.qt.io/qtcreator/index.html}{doc.qt.io}. - To build documentation for the sources from the qtcreator master branch, use - build scripts defined in the doc.pri file. To build the docs in the - HTML format and to create help files (.qch), enter the following build - commands from the project folder (after running qmake): + \section3 Using CMake - \list - \li \c {nmake docs} (on Windows) + When using CMake, the docs are built in the \QC \e {build folder} or a + separate doc build folder, not in the project folder. + + To get the correct product name and version when building \QDS Manual, you + must run CMake with the branding option. The branding data is located in + the \QDS (private) repository, \c tqtc-plugin-qtquickdesigner. - \li \c {make docs} (on Linux and \macos) + To build docs with CMake in a separate doc build folder: + + \list 1 + \li Create a folder for the built docs and switch to it. For example, + \c {C:\dev\qtc-doc-build}. + \li In the doc build folder, enter the following command: + \badcode + cmake -DWITH_DOCS=ON "-DCMAKE_PREFIX_PATH=<path_to_qt>" <path_to_qtcreator_src> + \endcode + For example (all on one line): + \badcode + C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON + "-DCMAKE_PREFIX_PATH=C:\Qt\5.15.1\msvc2019_64" + C:\dev\qtc-super\qtcreator + \endcode + \li To also build Extending \QC Manual, add the following option: + \c {-DBUILD_DEVELOPER_DOCS=ON} + \li To also build the \QDS Manual, add the following option: + \c {"-DCMAKE_MODULE_PATH=<absolute_path_to_qtquickdesignerrepo>/studiodata/branding/"} + + For example: + \badcode + C:\dev\qtc-doc-build>cmake -DWITH_DOCS=ON -DBUILD_DEVELOPER_DOCS=ON + "-DCMAKE_MODULE_PATH=C:\dev\tqtc-plugin-qtquickdesigner\studiodata\branding" + "-DCMAKE_PREFIX_PATH=C:\Qt\5.15.1\msvc2019_64" + C:\dev\qtc-super\qtcreator + \endcode + \li To build the docs using the online style, use the following option + instead of \c {-DWITH_DOCS=ON}: + \c {-DWITH_ONLINE_DOCS=ON} + + For example: + \badcode + C:\dev\qtc-doc-build>cmake -DWITH_ONLINE_DOCS=ON + -DBUILD_DEVELOPER_DOCS=ON + "-DCMAKE_MODULE_PATH=C:\dev\tqtc-plugin-qtquickdesigner\studiodata\branding" + "-DCMAKE_PREFIX_PATH=C:\Qt\5.15.1\msvc2019_64" + C:\dev\qtc-super\qtcreator + \endcode + \note If you already ran CMake \c {-DWITH_DOCS=ON} in a folder and + want to switch to only online docs in that folder, you need to turn + the offline docs off again: + \badcode + cmake -DWITH_DOCS=OFF -DWITH_ONLINE_DOCS=ON + \endcode + \li Enter the following doc build command to build both HTML docs and + the help files (.qch): + \badcode + cmake --build . --target docs + \endcode + \li Alternatively, to build only the HTML docs, enter: + \badcode + cmake --build . --target html_docs + \endcode \endlist - The HTML documentation is generated in the following folders: + \note You can enter \c cmake-gui to open the graphical CMake configuration + tool, where you can select build options. + + The HTML files for the documentation are generated in the following + folders: \list \li \c doc/html/qtcreator - \li \c doc/html/qtcreatordev + \li \c doc/html/qtcreator-dev \li \c doc/html/qtdesignstudio + \li \c doc/html/qtcreator-online + \li \c doc/html/qtcreator-dev-online + \li \c doc/html/qtdesignstudio-online \endlist - 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 + The help files (\c {.qch}) are generated in the \c {share/doc/qtcreator} + folder or in the \c {<application_name>.app/Contents/Resources/doc\} folder 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 + 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 for building a particular - document in a particular format: + \section3 Using qmake - \list - \li \c html_docs_qtcreator - build \QC Manual in help format, but do not - generate a help file + To build offline documentation using qmake: - \li \c html_docs_qtcreator-dev - build Extending \QC Manual in help - format, but do not generate a help file + \list 1 + \li In the project folder, run \c qmake from an installed Qt. + For example: + \badcode + C:\dev\qtc-super\qtcreator>..\..\..\Qt\5.15.1\msvc2019_64\bin\qmake.exe + \endcode + \li Enter the following doc build command: + \list + \li On Windows: \c {nmake docs} + \li On Linux and \macos: \c {make docs} + \endlist + \endlist - \li \c qch_docs_qtcreator - build \QC Manual in help format and generate - a help file (.qch) + To build online documentation using qmake: - \li \c qch_docs_qtcreator-dev - build Extending \QC Manual in help format - and generate a help file (.qch) + \list 1 + \li In the project folder, run \c qmake from an installed Qt with the + online configuration option. For example: + \badcode + C:\dev\qtc-super\qtcreator>..\..\..\Qt\5.15.1\msvc2019_64\bin\qmake.exe + "CONFIG+=build_online_docs" + \endcode + \li Enter the following doc build command: + \list + \li On Windows: \c {nmake html_docs} + \li On Linux and \macos: \c {make html_docs} + \endlist \endlist - \section3 Building the \QDS Manual - - To get the correct product name and version, you must run \c {qmake -r} on - \c {qtcreator.pro} with the \c IDE_BRANDING_PRI option set to the absolute - path of \c {ide_branding.pri} in the \QDS (private) repository. + To get the correct product name and version when building the \QDS + Manual, you must run \c {qmake -r} on \c {qtcreator.pro} with the + \c IDE_BRANDING_PRI option set to the absolute path of + \c {ide_branding.pri} in the \QDS (private) repository. For example, on Windows enter (all on one line): @@ -570,16 +648,71 @@ IDE_BRANDING_PRI=C:\dev\tqtc-plugin-qtquickdesigner\studiodata\branding\ide_branding.pri \endcode - To build the \QDS Manual: + To use the offline style to build the \QDS help with qmake: \list 1 - \li Run \c qmake from Qt 5.14.0, or later with the path to the branding - information as an option (all on one line): - - \c {<relative_path_to>/qmake.exe - qtcreator.pro -r - IDE_BRANDING_PRI=<absolute_path_to>ide_branding.pri} + \li In the \c {doc/qtdesignstudio} folder, run \c qmake from Qt 5.14.0, + or later with the path to the branding information as an option + (all on one line): + \badcode + <relative_path_to>/qmake.exe qtcreator.pro -r + IDE_BRANDING_PRI=<absolute_path_to>/ide_branding.pri + \endcode \li Run \c {make docs} on Linux and macOS or \c {nmake docs} on Windows. \endlist + + To use the online style to build the \QDS Manual with qmake: + + \list 1 + \li In the \c {doc/qtdesignstudio} folder, run \c qmake from Qt 5.14.0, + or later with the path to the branding information as an option + (all on one line): + \badcode + <relative_path_to>/qmake.exe qtcreator.pro -r + IDE_BRANDING_PRI=<absolute_path_to>/ide_branding.pri + \endcode + \li Run \c {make html_docs} on Linux and macOS or \c {nmake html_docs} + on Windows. + \endlist + + The HTML files for the offline documentation are generated in the following + folders: + + \list + \li \c doc/html/qtcreator + \li \c doc/html/qtcreator-dev + \li \c doc/qtdesignstudio/doc/html/qtdesignstudio + \endlist + + 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. + + The HTML files for the online documentation are generated in the following + folders: + + \list + \li \c doc/html/qtcreator-online + \li \c doc/html/qtcreator-dev-online + \li \c doc/qtdesignstudio/doc/html/qtdesignstudio-online + \endlist + + \section2 Additional Build Commands + + Besides \c docs and \c html_docs, you can use the following build targets: + + \list + \li \c html_docs_<doc_config_file_name> - build the document (qtcreator/ + qtcreator-dev/qtdesignstudio) in help format, but do not generate a + help file (.qch) + + \li \c html_docs_<doc_config_file_name>-online - build the document + (qtcreator/qtcreator-dev/qtdesignstudio) in online format + + \li \c qch_docs_<doc_config_file_name> - build the document (qtcreator/ + qtcreator-dev/qtdesignstudio) in help format and generate a + help file + \endlist */ |