Qt5DocumentationProject: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
(Gather writing guidelines into a category) |
||
| (7 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
[[Category:Writing Guidelines]] | |||
{{DISPLAYTITLE:Qt5 Documentation Renewal Project}} | |||
We are working on restructuring and renewing and fixing the Qt Reference Documentation for the Qt 5 release. This consists of several parts: | We are working on restructuring and renewing and fixing the Qt Reference Documentation for the Qt 5 release. This consists of several parts: | ||
* | * API documentation: C++ API, QML API, and JavaScript related functions | ||
* Examples and example documentation: shows how the | * Examples and example documentation: shows how the API are used | ||
* Overviews: explains the architecture and features of Qt | * Overviews: explains the architecture and features of Qt | ||
==Changes from Qt 4 to Qt 5== | == Changes from Qt 4 to Qt 5 == | ||
Here is a brief summary of the important changes in the Qt 5 documentation: | Here is a brief summary of the important changes in the Qt 5 documentation: | ||
* QDoc's binary is now ''qdoc'' whereas in Qt 4, the binary is called ''qdoc3'' | |||
* | * The documentation is ''modularized''. This means that the documentation for each module resides in their respective source directories. The directory ''doc/src'' is no longer used to contain overviews and API documentation | ||
* The documentation is ''modularized''. This means that the documentation for each module resides in their respective source directories. The directory ''doc/src'' is no longer used to contain overviews and | |||
* The Qt modules will have their own pages and they may be treated as separate projects with different release schedules. | * The Qt modules will have their own pages and they may be treated as separate projects with different release schedules. | ||
==Important Resources== | == Important Resources == | ||
These are important resources for contributing to or working with the documentation. | These are important resources for contributing to or working with the documentation. | ||
* [[Checklist for Adding Documentation for a New Module | Adding Documentation to a New Module]] | |||
* [[Writing_Qt_Documentation | Qt Documentation Wiki]] - the main Documentation wiki which contains style information and contribution details | |||
* [http://doc-snapshots.qt.io/qt5-dev/qdoc-index.html QDoc Manual] - contains a guide to QDoc as well as information about C++ and QML commands | |||
* [[Qt_Documentation_Structure | Documentation Structure]] page contains a map of how the directory structure of a repository or module should be | |||
* [[Building_Qt_Documentation | Building Qt Documentation]] - outlines how to build the documentation for Qt 5 and for each module | |||
* [[QtWritingGuidelines | Qt Writing Guidelines]] | |||
* [http://doc-snapshots.qt.io/ http://doc-snapshot.qt.io/] - the documentation snapshot | |||
== API Documentation in Qt 5 == | |||
= | |||
Essentially, each module needs: | Essentially, each module needs: | ||
* landing page (using the command) [[QtLandingPage | see specifications]] | |||
* landing page (using the | |||
* example page | * example page | ||
* c++ class list (using the | * c++ class list (using the command) | ||
* qml type list ( | * qml type list (command) | ||
To get started, the [http://doc- | To get started, the [http://doc-snapshots.qt.io/qdoc-guide.html QDoc Guide] explains how QDoc generates documentation from QDoc comments. | ||
==Overview Documentation== | == Overview Documentation == | ||
Overviews describe a functionality, a group of | Overviews describe a functionality, a group of APIs, and the technology in Qt. These overviews help developers decide which feature or API suits them best and helps them understand how the API cooperate within Qt and their applications. | ||
For Qt 5, many of the overviews are being edited and rewritten for correctness and relevancy. | For Qt 5, many of the overviews are being edited and rewritten for correctness and relevancy. | ||
==Example documentation== | == Example documentation == | ||
Examples have two components: | Examples have two components: | ||
* '''code''' - must compile and be delivered to the SDK. The ''.pro'' files must exist and SDK users must be able to compile them | |||
* '''code''' | * '''documentation''' - the documentation walks through the example code. This page is created by QDoc's '''' topic command | ||
* '''documentation''' | |||
A brief list of the tasks: | A brief list of the tasks: | ||
* Triage and sort the examples * - current status: [http://community.kde.org/Qt5/Documentation/ExampleList Example List] | |||
* Triage and sort the examples * | * Fix the example code - the examples must be modularized and follow the [[Qt_Documentation_Structure | documentation structure]]. | ||
* Fix the example code | |||
Latest revision as of 15:47, 25 November 2016
We are working on restructuring and renewing and fixing the Qt Reference Documentation for the Qt 5 release. This consists of several parts:
- API documentation: C++ API, QML API, and JavaScript related functions
- Examples and example documentation: shows how the API are used
- Overviews: explains the architecture and features of Qt
Changes from Qt 4 to Qt 5
Here is a brief summary of the important changes in the Qt 5 documentation:
- QDoc's binary is now qdoc whereas in Qt 4, the binary is called qdoc3
- The documentation is modularized. This means that the documentation for each module resides in their respective source directories. The directory doc/src is no longer used to contain overviews and API documentation
- The Qt modules will have their own pages and they may be treated as separate projects with different release schedules.
Important Resources
These are important resources for contributing to or working with the documentation.
- Adding Documentation to a New Module
- Qt Documentation Wiki - the main Documentation wiki which contains style information and contribution details
- QDoc Manual - contains a guide to QDoc as well as information about C++ and QML commands
- Documentation Structure page contains a map of how the directory structure of a repository or module should be
- Building Qt Documentation - outlines how to build the documentation for Qt 5 and for each module
- Qt Writing Guidelines
- http://doc-snapshot.qt.io/ - the documentation snapshot
API Documentation in Qt 5
Essentially, each module needs:
- landing page (using the command) see specifications
- example page
- c++ class list (using the command)
- qml type list (command)
To get started, the QDoc Guide explains how QDoc generates documentation from QDoc comments.
Overview Documentation
Overviews describe a functionality, a group of APIs, and the technology in Qt. These overviews help developers decide which feature or API suits them best and helps them understand how the API cooperate within Qt and their applications.
For Qt 5, many of the overviews are being edited and rewritten for correctness and relevancy.
Example documentation
Examples have two components:
- code - must compile and be delivered to the SDK. The .pro files must exist and SDK users must be able to compile them
- documentation - the documentation walks through the example code. This page is created by QDoc's ' topic command
A brief list of the tasks:
- Triage and sort the examples * - current status: Example List
- Fix the example code - the examples must be modularized and follow the documentation structure.