mirror of https://github.com/qt/qtdoc.git
Update top-level README
Update top-level README to be more accessible, both for humans and LLM's: * Switch to Markdown syntax, rename file * List the different documentation projects (qdocconf files), with details of the content and how to build it. * Defer for main building instructions to qt5.git, as a) a top-level qt5.git build is the most reliable way to build the documentation, and b) most advise here doesn't only apply to the *.qdocconf files in qtdoc.git. Change-Id: If903ec5283dcc6151e4628227637e422b98bc55e Reviewed-by: Paul Wicking <paul.wicking@qt.io>
This commit is contained in:
Kai Köhne
parent
7f3b507e79
commit
7d164a7451
87
README
87
README
|
|
@ -1,87 +0,0 @@
|
||||||
To Generate Qt Documentation:
|
|
||||||
|
|
||||||
qtdoc contains the main Qt Reference Documentation, which includes
|
|
||||||
overviews, Qt topics, and examples not specific to any Qt module.The
|
|
||||||
configuration files are located in qtdoc/doc/config and the articles in
|
|
||||||
qtdoc/doc/src. Note that QDoc is located in qttools/src/qdoc.
|
|
||||||
|
|
||||||
The instructions in this file assumes that the prerequisite binaries are
|
|
||||||
compiled and in the $PATH variable.
|
|
||||||
|
|
||||||
Prerequisites:
|
|
||||||
* qtbase exists
|
|
||||||
* "qdoc" built and installed
|
|
||||||
* other Qt repositories exist as needed
|
|
||||||
|
|
||||||
The Qt Reference Documentation was written with links to the released modules
|
|
||||||
for Qt. If the modules and repositories do not exist, then the resulting HTML
|
|
||||||
files will contain broken links.
|
|
||||||
|
|
||||||
There are two ways to build the documentation. One way is to compile the
|
|
||||||
documentation using QDoc and the configuration file (qdocconf) file. The other
|
|
||||||
way is to use CMake and Ninja by running "ninja docs".
|
|
||||||
|
|
||||||
Section 1 Building the qdocconf File
|
|
||||||
|
|
||||||
This method is useful for building separate projects without any
|
|
||||||
dependencies to other projects.
|
|
||||||
|
|
||||||
To build using the qdocconf file, run the "qdoc" binary and pass the
|
|
||||||
qdocconf file as a parameter. "qdoc" is found in qttools repository. A
|
|
||||||
mandatory "outputdir" must be specified.
|
|
||||||
|
|
||||||
$> qdoc doc/config/qtdoc.qdocconf -outputdir html
|
|
||||||
|
|
||||||
Note that QDoc will delete the contents of the "html" output directory.
|
|
||||||
|
|
||||||
Section 2 Building using CMake and Ninja
|
|
||||||
|
|
||||||
QMake uses the QT_INSTALL_DOCS variable to determine where the documentation
|
|
||||||
for Qt is installed. This method is useful for linking to other Qt modules.
|
|
||||||
|
|
||||||
To see where the documentation will be installed, run:
|
|
||||||
$> <Qt-installation-dir>/bin/qtpaths -query QT_INSTALL_DOCS
|
|
||||||
|
|
||||||
To generate the documentation, run:
|
|
||||||
|
|
||||||
$> cd qtdoc #or whichever repository's root
|
|
||||||
$> <Qt-installation-dir>/bin/qt-configure-module .
|
|
||||||
$> ninja docs
|
|
||||||
$> ninja install
|
|
||||||
|
|
||||||
This procedure also works in the top-level Qt repository. Running the
|
|
||||||
commands there will generate the documentation for Qt and install them to
|
|
||||||
the path set to the QT_INSTALL_DOCS variable.
|
|
||||||
|
|
||||||
Section 3 Building Qt Documentation
|
|
||||||
|
|
||||||
To build the Qt module documentation along with the Qt Reference Documentation,
|
|
||||||
run the following:
|
|
||||||
|
|
||||||
$> cd qt # the top-level Qt repository
|
|
||||||
$> configure # creates the build system for all repositories
|
|
||||||
$> ninja docs
|
|
||||||
|
|
||||||
To generate only HTML files, run "ninja html_docs" instead of "ninja docs".
|
|
||||||
|
|
||||||
Section 4 Packaging the Documentation
|
|
||||||
|
|
||||||
Required binaries:
|
|
||||||
* qhelpgenerator - found in qttools
|
|
||||||
|
|
||||||
To compile the qch file for each module, first enter the output directory
|
|
||||||
which contains the .qhp file and generate the QCH file.
|
|
||||||
|
|
||||||
$> cd qtbase/doc/qtdoc #the default path for QT_INSTALL_DOCS for qtdoc
|
|
||||||
$> qhelpgenerator qtdoc.qhp #creates the QCH file called qtdoc.qch
|
|
||||||
|
|
||||||
Alternatively, modules have a "qch_docs" target:
|
|
||||||
$> cd qtbase
|
|
||||||
$> make qch_docs #builds the QCH files for modules in qtbase
|
|
||||||
|
|
||||||
The QCH file can then be loaded in Qt Creator.
|
|
||||||
|
|
||||||
Section 5 More Information
|
|
||||||
|
|
||||||
For more information about Qt's documentation, refer to the Qt Project wiki:
|
|
||||||
https://wiki.qt.io/Qt_Writing_Guidelines
|
|
||||||
|
|
@ -0,0 +1,95 @@
|
||||||
|
# Qt Documentation
|
||||||
|
|
||||||
|
This repository contains the main Qt Reference Documentation, including
|
||||||
|
overviews, Qt topics, examples, and tutorials not specific to any Qt module.
|
||||||
|
|
||||||
|
|
||||||
|
## Documentation Projects
|
||||||
|
|
||||||
|
The documentation is organized into several documentation projects:
|
||||||
|
|
||||||
|
|
||||||
|
### QtDoc
|
||||||
|
|
||||||
|
The main Qt Reference Documentation.
|
||||||
|
|
||||||
|
Project File: doc/config/qtdoc.qdocconf
|
||||||
|
|
||||||
|
Sources: `doc/src/` (excluding `cmake/` and `platformintegration/`
|
||||||
|
subdirectories)
|
||||||
|
|
||||||
|
Content:
|
||||||
|
- Getting started guides and tutorials
|
||||||
|
- Platform-specific documentation (Android, iOS, macOS, Windows, etc.)
|
||||||
|
- Qt modules overview and reference
|
||||||
|
- Development tools and utilities
|
||||||
|
- Legal information and licenses
|
||||||
|
- Examples and demos
|
||||||
|
|
||||||
|
CMake Targets: `docs_QtDoc` or `html_docs_QtDoc`
|
||||||
|
|
||||||
|
This project also contains the documentation for examples and tutorials in
|
||||||
|
the `examples/` directory.
|
||||||
|
|
||||||
|
|
||||||
|
### QtCMake
|
||||||
|
|
||||||
|
Documentation for using Qt with CMake.
|
||||||
|
|
||||||
|
Project File: doc/src/cmake/qtcmake.qdocconf
|
||||||
|
|
||||||
|
Sources: `doc/src/cmake`
|
||||||
|
|
||||||
|
Content:
|
||||||
|
- CMake manual and getting started guide
|
||||||
|
- Qt CMake API reference
|
||||||
|
- Build system configuration
|
||||||
|
|
||||||
|
CMake Targets: `docs_qtcmake` or `html_docs_qtcmake`.
|
||||||
|
|
||||||
|
|
||||||
|
### QtPlatformIntegration
|
||||||
|
|
||||||
|
Documentation for integrating Qt with native platforms.
|
||||||
|
|
||||||
|
Project File: doc/src/platformintegration/qtplatformintegration.qdocconf
|
||||||
|
|
||||||
|
Sources: `doc/src/platformintegration/`
|
||||||
|
|
||||||
|
Content:
|
||||||
|
- Qt Platform Abstraction (QPA)
|
||||||
|
- Platform-specific integration guides
|
||||||
|
- Native API interaction
|
||||||
|
|
||||||
|
CMake Targets: `docs_QtPlatformIntegration` or `html_docs_QtPlatformIntegration`.
|
||||||
|
|
||||||
|
|
||||||
|
## Building Documentation
|
||||||
|
|
||||||
|
The main QtDoc documentation contains links to pages from other documentation
|
||||||
|
projects (QtCore, QtQuick, etc.). Similarly, these projects link back to
|
||||||
|
pages and topics in QtDoc.
|
||||||
|
|
||||||
|
Therefore, the most reliable approach is to build Qt documentation as part of
|
||||||
|
a complete Qt build that includes all supported Qt modules. Refer to the
|
||||||
|
README.md in qt5.git for detailed instructions.
|
||||||
|
|
||||||
|
## Building Examples
|
||||||
|
|
||||||
|
Build the examples by opening the CMakeLists.txt files in the respective
|
||||||
|
example directory.
|
||||||
|
|
||||||
|
|
||||||
|
## Writing and Improving Qt Documentation
|
||||||
|
|
||||||
|
Qt Documentation is written in QDoc syntax. See
|
||||||
|
https://doc.qt.io/qt-6/qdoc-index.html for the QDoc manual.
|
||||||
|
|
||||||
|
For more information about Qt's documentation, refer to the Qt Project wiki:
|
||||||
|
https://wiki.qt.io/Qt_Writing_Guidelines
|
||||||
|
|
||||||
|
|
||||||
|
## Writing and Improving Qt Examples
|
||||||
|
|
||||||
|
See https://contribute.qt-project.org/quips/13 for some guidance around the
|
||||||
|
Qt examples.
|
||||||
Loading…
Reference in New Issue