Category:Developing Qt::Documentation: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
No edit summary
(Add 'docs as code' remark, add tip to use ' git grep' to locate documentation in source code.)
 
(32 intermediate revisions by 11 users not shown)
Line 1: Line 1:
=Developing Qt Documentation=
[[Category:Developing Qt]]


Qt documentation is written by a small global team of technical writers and developers working at Digia Plc, complemented by a number of contributors from other parts of the Qt community. Since different parts of Qt are developed in different locations, writers with expertize in those areas are typically co-located with those developers. For example, much of the documentation for Qt Creator and the Qt <span class="caps">SDK</span> is written in Berlin.
Qt documentation is written by a small global team of technical writers and developers working at The Qt Company, complemented by a number of contributors from other parts of the Qt community. Since different parts of Qt are developed in different locations, writers with expertise in a particular area are typically co-located with the developers of that area. For example, the documentation for Qt Creator is written in Berlin.


Qt’s technical writers are also responsible for many of the examples provided with Qt and related projects. However, the demonstrations provided with these projects are typically created by developers, and these are often not intended to be documented or supported by the Qt documentation team.
Qt's technical writers are also responsible for many of the examples provided with Qt and related projects. However, the demonstrations provided with these projects are typically created by developers, and these are often not intended to be documented or supported by the Qt documentation team.


The documents in this category aim to cover the many aspects of Qt documentation creation, including the process we use to accept contributions from other community members.
The documents in this category aim to cover the many aspects of Qt documentation creation, including the process we use to accept contributions from other community members.
Line 11: Line 11:
Currently, Qt documentation is hosted at three sites:
Currently, Qt documentation is hosted at three sites:


* [http://doc.qt.io/ Qt Project] ''[doc.qt.io]'' – contains official releases
*[http://doc.qt.io/ doc.qt.io]: contains official releases
* [http://doc-snapshot.qt.io Snapshot] ''[doc-snapshot.qt.io]'' – contains unreleased documentation from the [http://codereview.qt.io Codereview] ''[codereview.qt.io]'' repositories
*[http://doc-snapshots.qt.io/ snapshots]: contains unreleased documentation from the [http://codereview.qt-project.org/ Codereview] repositories
* [http://doc.qt.digia.com Archives] ''[doc.qt.digia.com]'' – contains legacy documentation
*[http://doc.qt.io/archives/ archives]: contains legacy documentation


==Contributing to Qt Documentation==
==Contributing to Qt Documentation==
Qt Project follows a 'docs as code' approach. That is, the documentation is maintained in the form of markup (qdoc), and is maintained
alongside the source code of the Qt modules and tools it is describing, using the same version control system and a similar
[[Qt Contribution Guidelines | contribution process]].


===Prerequisites===
===Prerequisites===
Line 21: Line 25:
Here are the basic steps to help you get started contributing to the Qt documentation:
Here are the basic steps to help you get started contributing to the Qt documentation:


# Familiarize yourself with the [[Developing-Qt|development process]]. In particular, [[Qt-Contribution-Guidelines|the process of contributing code]].
#Familiarize yourself with the [[:Category:Developing_Qt | development process]]. In particular, [[Qt Contribution Guidelines | the process of contributing code]].
# Create a [https://bugreports.qt.io Jira] ''[bugreports.qt.io]'' account and set up your [[Setting-up-Gerrit|Gerrit]] environment.
#Create a [https://bugreports.qt.io Jira] account and set up your [[Setting up Gerrit | Gerrit]] environment.
# [[Get The Source|Download]] the Qt sources.
#[[Get_The_Source | Download]] the Qt sources.
# Read the page regarding [[Code Reviews|code reviews]].
#Read the page regarding [[Code_Reviews | code reviews]].
#Start by contributing small fixes. Don't hesitate to ask for help!
 
===Style and Language Guidelines===
Qt documentation adheres to the [https://docs.microsoft.com/en-us/style-guide/welcome/ Microsoft Style Guide]. The documentation follows American English grammar and spelling.
 
The [[Language_Guidelines | Language Guidelines]] page provides further information about idioms and usage, punctuation and grammar issues.


===QDoc and Style Guidelines===
===QDoc===


Qt’s documentation tool is QDoc. QDoc scans through the source and generates html pages regarding the classes, enums, <span class="caps">QML</span> types, and other parts of the <br /> reference documentation.
Qt's documentation tool is QDoc. QDoc scans through the source and generates html pages regarding the classes, enums, QML types, and other parts of the
reference documentation.


* [http://doc-snapshot.qt.io/qdoc/ QDoc Manual] ''[doc-snapshot.qt.io]''
*[http://doc-snapshots.qt.io/qt6-dev/qdoc-index.html QDoc Manual]


To get started, the [http://doc.qt.io/qt-5/qdoc-guide.html QDoc Guide] ''[doc.qt.io]'' explains how QDoc generates documentation from QDoc comments.
To get started, the [http://doc.qt.io/qt-5/qdoc-guide.html QDoc Guide] explains how QDoc generates documentation from QDoc comments.


===QDoc Regression Testing===
===QDoc Regression Testing===


* [[QDocRegressionTesting]]
*[[QDocRegressionTesting]]


===Writing Guidelines===
===[[:Category:Writing Guidelines]]===


* [[QtWritingGuidelines]]
*[[Qt Writing Guidelines]]


===Submitting a Patch===
===Submitting a Patch===


The process for submitting a documentation patch is the same as for source code. For more information, read the [[Code Reviews]] page.
The process for submitting a documentation patch is the same as for source code. For more information, read the [[Code_Reviews | Code Reviews]] page.
 
Tip: Use [https://git-scm.com/docs/git-grep git grep] to find the file and line where existing documentation is maintained.


====Approvers and Editors====
====Approvers and Editors====


For language reviews, documentation reviews, and technical reviews, you may add any of the relevant [[maintainers]] as reviewers as well as the following individuals:
For language reviews, documentation reviews, and technical reviews, you may add any of the relevant [[Maintainers | maintainers]] as reviewers as well as the following individuals:


* Leena Miettinen (Qt Creator documentation maintainer)
*[[User:Andreaseliasson|Andreas Eliasson]]
* Geir Vattekar
*Esa Törmänen (Qt for MCU documentation)
* Jerome Pasion
*Inkamari Harjula (Boot2Qt documentation)
* Venugopal Shivashankar
*[[User:Jaishreevyas|Jaishree Vyas]] (Qt Foundations)
* Martin Smith
*[[User:Johannavanhatapio|Johanna Vanhatapio]] (Qt Design Studio  documentation)
* Nico Vertriest
*[[User:Leenamiettinen|Leena Miettinen]] (Qt Creator documentation maintainer)
* Topi Reinio (Documentation maintainer)
*[[User:Lucadisera|Luca Di Sera]]
* Sze Howe Koh
*[[User:Matshonkamaa|Mats Honkamaa]] (Qt Design Studio  documentation)
*[[User:Nicholasbennet|Nicholas Bennet]] (Platform documentation)
*[[User:Paulwicking|Paul Wicking]]
*Pranta Dastider (Qt Design Studio  documentation)
*Safiyyah Moosa
*[[User:Topireinio|Topi Reiniö]] (QDoc maintainer)
*[[User:Venugopalshivashankar|Venugopal Shivashankar]]
*[[User:Szehowekoh|Sze Howe Koh]]


For language reviews (particularly for non-native English speakers) only, you may also add any of the following individuals:
For language reviews (particularly for non-native English speakers) only, you may also add any of the following individuals:


* Mitch Curtis
*Mitch Curtis
* Lorn Potter
*Lorn Potter
*[[User:EdwardWelbourne|Edward Welbourne]]


For documentation help, join the #qt-documentation channel in Freenode.
For documentation help, join the #qt-documentation channel in Freenode.
Line 68: Line 89:
===Filing Documentation Issues===
===Filing Documentation Issues===


Anybody with a [https://bugreports.qt.io Jira] ''[bugreports.qt.io]'' account may file a bug. For documentation bugs, please file the issue and enter ''Documentation'' '''<span class="caps">AND</span>''' the relevant library or module in the Component field. The process of fixing code bugs also apply to documentation issues.
Anybody with a [https://bugreports.qt.io/ Jira] account may file a bug. For documentation bugs, please file the issue and enter ''Documentation'' '''AND''' the relevant library or module in the Component field. The process of fixing code bugs also apply to documentation issues.


The latest documentation snapshot is at http://doc-snapshot.qt.io/ ''[doc-snapshot.qt.io]''
Before filing an issue, please check that it has not already been fixed in a later version of the documentation.
The latest documentation snapshots are at [http://doc-snapshots.qt.io/ doc-snapshots.qt.io]


==Qt 5 Documentation==
==Modular Qt Documentation==


The organization and development of Qt 5 documentation is covered in another wiki: [[Qt5DocumentationProject]]
The organization and development of modular Qt documentation is covered in another wiki: [[Qt5DocumentationProject]]


===Documentation Structure===
===Documentation Structure===


The [[Qt Documentation Structure]] page provides information about the structure of the documentation.
The [[Qt_Documentation_Structure | Qt Documentation Structure]] page provides information about the structure of the documentation.
 
===There are 9 articles in "Developing_Qt -&gt; Documentation":===
 
===B===
* [[Building Qt Documentation|Building_Qt_Documentation]]
* [[Building Qt Documentation Japanese|Building_Qt_Documentation_Japanese]]
* [[Building Qt Documentation Korean|Building_Qt_Documentation_Korean]]
* [[Building Qt Documentation Russian|Building_Qt_Documentation_Russian]]
* [[Building Qt Documentation SimplifiedChinese|Building_Qt_Documentation_SimplifiedChinese]]===I===
* [[Integrating Qt Examples SimplifiedChinese|Integrating_Qt_Examples_SimplifiedChinese]]===Q===
* [[Qt Example Coverage|Qt_Example_Coverage]]===S===
* [[Spelling Module Names in Qt Documentation|Spelling_Module_Names_in_Qt_Documentation]]===T===
* [[Troubleshooting Qt Documentation|Troubleshooting_Qt_Documentation]]

Latest revision as of 14:01, 15 April 2024


Qt documentation is written by a small global team of technical writers and developers working at The Qt Company, complemented by a number of contributors from other parts of the Qt community. Since different parts of Qt are developed in different locations, writers with expertise in a particular area are typically co-located with the developers of that area. For example, the documentation for Qt Creator is written in Berlin.

Qt's technical writers are also responsible for many of the examples provided with Qt and related projects. However, the demonstrations provided with these projects are typically created by developers, and these are often not intended to be documented or supported by the Qt documentation team.

The documents in this category aim to cover the many aspects of Qt documentation creation, including the process we use to accept contributions from other community members.

Documentation Snapshots

Currently, Qt documentation is hosted at three sites:

Contributing to Qt Documentation

Qt Project follows a 'docs as code' approach. That is, the documentation is maintained in the form of markup (qdoc), and is maintained alongside the source code of the Qt modules and tools it is describing, using the same version control system and a similar contribution process.

Prerequisites

Here are the basic steps to help you get started contributing to the Qt documentation:

  1. Familiarize yourself with the development process. In particular, the process of contributing code.
  2. Create a Jira account and set up your Gerrit environment.
  3. Download the Qt sources.
  4. Read the page regarding code reviews.
  5. Start by contributing small fixes. Don't hesitate to ask for help!

Style and Language Guidelines

Qt documentation adheres to the Microsoft Style Guide. The documentation follows American English grammar and spelling.

The Language Guidelines page provides further information about idioms and usage, punctuation and grammar issues.

QDoc

Qt's documentation tool is QDoc. QDoc scans through the source and generates html pages regarding the classes, enums, QML types, and other parts of the reference documentation.

To get started, the QDoc Guide explains how QDoc generates documentation from QDoc comments.

QDoc Regression Testing

Category:Writing Guidelines

Submitting a Patch

The process for submitting a documentation patch is the same as for source code. For more information, read the Code Reviews page.

Tip: Use git grep to find the file and line where existing documentation is maintained.

Approvers and Editors

For language reviews, documentation reviews, and technical reviews, you may add any of the relevant maintainers as reviewers as well as the following individuals:

For language reviews (particularly for non-native English speakers) only, you may also add any of the following individuals:

For documentation help, join the #qt-documentation channel in Freenode.

Filing Documentation Issues

Anybody with a Jira account may file a bug. For documentation bugs, please file the issue and enter Documentation AND the relevant library or module in the Component field. The process of fixing code bugs also apply to documentation issues.

Before filing an issue, please check that it has not already been fixed in a later version of the documentation. The latest documentation snapshots are at doc-snapshots.qt.io

Modular Qt Documentation

The organization and development of modular Qt documentation is covered in another wiki: Qt5DocumentationProject

Documentation Structure

The Qt Documentation Structure page provides information about the structure of the documentation.

Subcategories

This category has only the following subcategory.

W

Pages in category "Developing Qt::Documentation"

The following 4 pages are in this category, out of 4 total.

B

Q

T

Retrieved from "https://wiki.qt.io/index.php?title=Category:Developing_Qt::Documentation&oldid=41704"