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