Doc: Describe new Qt for Python support features

Add an overview page for Developing Qt for Python applications.
It contains links to Python-related information in the manual
and some sections about setting up the development environment.

Task-number: QTCREATORBUG-28996
Change-Id: If5a442415bad65aa94aa78183d44c6e0f78e317e
Reviewed-by: Shyamnath Premnadh <Shyamnath.Premnadh@qt.io>

doc/qtcreator/src/editors/creator-coding.qdoc

@@ -85,6 +85,13 @@
             \l{https://github.com/features/copilot}{GitHub Copilot} into \QC.
             You can view suggestions from Copilot in the code editor.
 
+        \li \l{Developing Qt for Python Applications}
+
+            To support developing Qt for Python applications, \QC lets you
+            set up Qt for Python, use project wizards to create Qt for
+            Python applications, write Python code, and run and debug the
+            applications.
+
         \li \l{Editing MIME Types}
 
             \QC uses the MIME type of a file to determine which mode and editor

doc/qtcreator/src/editors/creator-only/creator-copilot.qdoc

@@ -4,7 +4,7 @@
 /*!
     \previouspage creator-language-servers.html
     \page creator-copilot.html
-    \nextpage creator-mime-types.html
+    \nextpage creator-python-development.html
 
     \title Using GitHub Copilot
 

doc/qtcreator/src/editors/creator-only/creator-mime-types.qdoc

@@ -8,7 +8,7 @@
 // **********************************************************************
 
 /*!
-    \previouspage creator-copilot.html
+    \previouspage creator-python-development.html
     \page creator-mime-types.html
     \nextpage creator-modeling.html
 

doc/qtcreator/src/python/creator-python-development.qdoc

@@ -0,0 +1,96 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \page creator-python-development.html
+    \previouspage creator-copilot.html
+    \nextpage creator-mime-types.html
+
+    \title Developing Qt for Python Applications
+
+    \l {https://doc.qt.io/qtforpython/index.html}{Qt for Python} enables you
+    to use Qt 6 API in Python applications. You can use the PySide6 modules
+    to gain access to individual Qt modules, such as \l {Qt Core}, \l {Qt GUI},
+    and \l {Qt Widgets}.
+
+    The following sections describe using \QC for developing with Qt for Python:
+
+    \list
+        \li \l{Creating Widget-Based Qt for Python Applications}
+            {Creating Qt for Python Applications}
+        \li \l{Setting Up PySide6}
+        \li \l{Selecting the Python Interpreter}
+        \li \l{Creating a Virtual Environment}
+        \li \l{Using Python Interactive Shell}
+        \li \l{Python Language Server}
+        \li \l{Running Python Projects}
+        \li \l{Specifying Run Settings for Python Projects}
+        \li \l{PDB}
+        \li \l{Launching the Debugger}
+    \endlist
+
+    For more information about developing with Qt for Python, including
+    limitations, see \l {https://doc.qt.io/qtforpython/index.html}
+    {Qt for Python}.
+
+    \section1 Setting Up PySide6
+
+    If you have not installed the required version of PySide6, \QC prompts you to
+    do so when you open a .py file.
+
+    \image qtcreator-python-install.webp {Prompts to install PySide6 and Python language server}
+
+    Further, \QC prompts you to install the \l {Python Language Server}
+    {Python language server} that offers services such as code completion
+    and annotations. Select \uicontrol Install to install PySide6 and the
+    language server.
+
+    \section1 Selecting the Python Interpreter
+
+    You select the initial Python interpreter when you use the Qt for Python
+    Application wizard templates to create Python projects.
+
+    \image qtcreator-python-wizard-define-python-interpreter.webp {Define Python Interpreter wizard page}
+
+    You can see the current Python interpreter on the \uicontrol Edit mode
+    toolbar.
+
+    \image qtcreator-python-interpreter-edit-mode.webp {Python interpreter on the Edit mode toolbar}
+
+    You can change the interpreter to use for a particular project in
+    \uicontrol Projects > \uicontrol Run > \uicontrol Interpreter.
+
+    \image qtcreator-python-run-settings.png {Python run settings}
+
+    To see the available interpreters and choose another interpreter, select the
+    current interpreter, and then select \uicontrol {Manage Python Interpreters}.
+    Or, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Python >
+    \uicontrol Interpreters.
+
+    \image qtcreator-python-interpreters.png {Python Interpreters in Preferences}
+
+    You can add and remove interpreters and clean up references to interpreters
+    that you uninstalled, but that still appear in the list. In addition, you
+    can set the interpreter to use by default.
+
+    \section1 Creating a Virtual Environment
+
+    To create a virtual environment (\c venv) when you use the Qt for
+    Python Application wizard templates to create Python projects, select
+    the \uicontrol {Create new virtual environment} check box on the
+    \uicontrol {Define Python Interpreter} wizard page. Specify the
+    directory where to create the environment in
+    \uicontrol {Path to virtual environment}.
+
+    \section1 Using Python Interactive Shell
+
+    You can write Python code in the Edit mode. Select \uicontrol REPL on the
+    toolbar to start the \l{https://pythonprogramminglanguage.com/repl/}
+    {Python interactive shell} in the \l Terminal pane.
+
+    \image qtcreator-terminal-python.webp {Python shell on the taskbar}
+
+    To start the shell and import the current file as a module, select
+    \uicontrol {REPL Import File}. To also import all functions from
+    the file, select \uicontrol {REPL Import *}.
+*/

doc/qtcreator/src/python/creator-python-project.qdocinc

@@ -1,4 +1,4 @@
-// Copyright (C) 2021 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
@@ -6,38 +6,12 @@
 
     \section2 Creating Widget-Based Qt for Python Applications
 
-    \l {https://doc.qt.io/qtforpython/index.html}{Qt for Python} enables you
-    to use Qt 6 API in Python applications. You can use the PySide6 modules
-    to gain access to individual Qt modules, such as \l {Qt Core}, \l {Qt GUI},
-    and \l {Qt Widgets}.
-
-    If you have not installed PySide6, \QC prompts you to install it after
-    you create the project. Further, it prompts you to install the
-    \l {Python Language Server}{Python language server} that offers services
-    such as code completion and annotations. Select \uicontrol Install to install
-    PySide6 and the language server.
-
-    You can see the current Python interpreter on the \uicontrol Edit mode
-    toolbar.
-
-    \image qtcreator-python-interpreter-edit-mode.webp {Python interpreter on the Edit mode toolbar}
-
-    To see the available interpreters and change their paths, select
-    the interpreter, and then select \uicontrol {Manage Python Interpreters}.
-    Or, select \uicontrol Edit > \uicontrol Preferences > \uicontrol Python >
-    \uicontrol Interpreters.
-
-    \image qtcreator-python-interpreters.png {Python Interpreters in Preferences}
-
-    You can add and remove interpreters and clean up references to interpreters
-    that you uninstalled, but that still appear in the list. In addition, you
-    can set the interpreter to use by default.
-
     The Qt for Python Application wizards generate a \c {.pyproject} file that
-    lists the files in the Python project and a \c {.py} file that has
+    lists the files in the \l{Developing Qt for Python Applications}{Python}
-    some boilerplate code. In addition, the widget-based UI wizard creates a
+    project and a \c {.py} file that has some boilerplate code. In addition, the
-    \c {.ui} file that has a \QD form, and the Qt Quick Application wizard
+    widget-based UI wizard creates a \c {.ui} file that has a \QD form, and the
-    creates a \c {.qml} file that has Qt Quick controls.
+    Qt Quick Application wizard creates a \c {.qml} file that imports Qt Quick
+    controls.
 
     The \c{.pyproject} files are JSON-based configuration files that replace
     the previously used \c {.pyqtc} configuration files. You can still open and
@@ -49,7 +23,7 @@
     the PySide version, class name, base class, and source file for the
     class.
 
-    \image qtcreator-python-wizard-app-window.png {Qt for Python wizard for creating a widget-based UI}
+    \image qtcreator-python-wizard-app-window.png {Define Class wizard page}
 
     The wizard adds the imports to the source file for
     access to the QApplication, the base class you selected in the Qt
@@ -121,13 +95,8 @@
     \endcode
 
     You can now modify the boilerplate code in the Edit mode to develop your
-    Python application. Select \uicontrol REPL on the toolbar to start the
+    Python application. Always regenerate the Python code after modifying a
-    \l{https://pythonprogramminglanguage.com/repl/}{Python interactive shell}.
+    UI file.
-    To start the shell and import the current file as a module, select
-    \uicontrol {REPL Import File}. To also import all functions from
-    the file, select \uicontrol {REPL Import *}.
-
-    Always regenerate the Python code after modifying a UI file.
 
     Open the .ui file in the \uicontrol Design mode to create a widget-based UI
     in \QD.

doc/qtcreator/src/python/creator-python-run.qdocinc

@@ -23,7 +23,7 @@
 
     You can specify settings for running Qt for Python applications:
 
-    \image qtcreator-python-run-settings.png
+    \image qtcreator-python-run-settings.png {Python run settings}
 
     \list
         \li In the \uicontrol Interpreter field, specify the path to the

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -131,6 +131,7 @@
             \li \l{Editing Markdown Files}
             \li \l{Using Language Servers}
             \li \l{Using GitHub Copilot}
+            \li \l{Developing Qt for Python Applications}
             \li \l{Editing MIME Types}
             \li \l{Modeling}
             \li \l{Editing State Charts}

doc/qtdesignstudio/config/qtdesignstudio.qdocconf

@@ -51,6 +51,7 @@ excludedirs  += ../../qtcreator/examples/accelbubble \
                 ../../qtcreator/src/meson \
                 ../../qtcreator/src/overview/creator-only \
                 ../../qtcreator/src/projects \
+                ../../qtcreator/src/python \
                 ../../qtcreator/src/qnx \
                 ../../qtcreator/src/qtquick/creator-only \
                 ../../qtcreator/src/vcs/creator-only \