diff --git a/README b/README deleted file mode 100644 index 035e233d8..000000000 --- a/README +++ /dev/null @@ -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: - $> /bin/qtpaths -query QT_INSTALL_DOCS - - To generate the documentation, run: - - $> cd qtdoc #or whichever repository's root - $> /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 diff --git a/README.md b/README.md new file mode 100644 index 000000000..c9aff5944 --- /dev/null +++ b/README.md @@ -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.