diff options
Diffstat (limited to 'sources/pyside6/doc/gettingstarted/index.rst')
-rw-r--r-- | sources/pyside6/doc/gettingstarted/index.rst | 149 |
1 files changed, 84 insertions, 65 deletions
diff --git a/sources/pyside6/doc/gettingstarted/index.rst b/sources/pyside6/doc/gettingstarted/index.rst index c65aa7abd..51d8bea26 100644 --- a/sources/pyside6/doc/gettingstarted/index.rst +++ b/sources/pyside6/doc/gettingstarted/index.rst @@ -4,7 +4,7 @@ Getting Started .. important:: This page is focused on building |project| **from source**. If you just want to install |pymodname|, you need to run: :command:`pip install pyside6`. - For more details, refer to our `Quick Start`_ guide. Additionally, you can check the + For more details, refer to our :ref:`quick-start` guide. Additionally, you can check the :ref:`FAQ <faq>` related to the project. .. _Quick Start: quickstart.html @@ -17,14 +17,16 @@ On **Linux** you might get them with your operating system package manager, on * you might get them with ``brew``, and on **Windows** you can download the installer from each website. - * **Python**: 3.7+ `[official Python website] <https://www.python.org/downloads/>`_ - * **Qt:** 6.4+ `[online installer] <https://download.qt.io/official_releases/online_installers/>`_ - * **CMake:** 3.18+ `[official CMake website] <https://cmake.org/download/>`_ - * **Git:** 2.0+. `[official Git website] <https://git-scm.com/downloads>`_ - * **libclang:** The libclang library, recommended: version 10 for 6.0+. - Prebuilt versions for each OS can be `downloaded here`_. +* **Python**: 3.9+ `[official Python website] <https://www.python.org/downloads/>`_ +* **Qt:** 6.8+ `[online installer] <https://download.qt.io/official_releases/online_installers/>`_ +* **CMake:** 3.18+ `[official CMake website] <https://cmake.org/download/>`_ +* **Git:** 2.0+. `[official Git website] <https://git-scm.com/downloads>`_ +* **libclang:** The libclang library, recommended: version 16+ for 6.8+. + Prebuilt versions for each OS can be `downloaded here`_. +* Check the `Supported Platforms of Qt`_ .. _downloaded here: https://download.qt.io/development_releases/prebuilt/libclang/ +.. _`Supported Platforms of Qt` : https://doc.qt.io/qt-6/supported-platforms.html Guides per platform ------------------- @@ -41,38 +43,44 @@ Guides per platform You can refer to the following pages for platform specific instructions: -.. panels:: - :body: align-items-center jutify-content-center text-center - :container: container-lg pb-3 - :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2 - :img-top-cls: d-flex align-self-center img-responsive card-img-top-main +.. grid:: 1 3 3 3 + :gutter: 2 - :img-top: ../images/windows.svg + .. grid-item-card:: + :img-top: ../images/windows.svg + :class-item: text-center - +++ + +++ + .. button-ref:: windows + :color: primary + :outline: + :expand: - .. link-button:: windows - :type: ref - :text: Windows - :classes: btn-qt btn-block stretched-link - --- - :img-top: ../images/macos.svg + Windows - +++ + .. grid-item-card:: + :img-top: ../images/macos.svg + :class-item: text-center - .. link-button:: macOS - :type: ref - :text: macOS - :classes: btn-qt btn-block stretched-link - --- - :img-top: ../images/linux.svg + +++ + .. button-ref:: macOS + :color: primary + :outline: + :expand: - +++ + macOS - .. link-button:: linux - :type: ref - :text: Linux - :classes: btn-qt btn-block stretched-link + .. grid-item-card:: + :img-top: ../images/linux.svg + :class-item: text-center + + +++ + .. button-ref:: linux + :color: primary + :outline: + :expand: + + Linux .. important:: |project| does not yet support WebAssembly and the mobile operating systems (Android or iOS). Most Linux-based embedded OS provide PySide with their official @@ -96,9 +104,9 @@ using **ninja** (instead of make), and considering only the **module subset** of :mod:`QtCore <PySide6.QtCore>`, :mod:`QtGui <PySide6.QtGui>`, and :mod:`QtWidgets <PySide6.QtWidgets>`. +`CMake Unity Build Mode`_ is used by default for speed-up. + Other important options to consider are: - * ``--unity``, Activates `CMake Unity Build Mode`_, which speeds up the - build by concatenating source files, * ``--cmake``, to specify the path to the cmake binary, * ``--reuse-build``, to rebuild only the modified files, * ``--openssl=/path/to/openssl/bin``, to use a different path for OpenSSL, @@ -135,7 +143,7 @@ Cross Compilation ----------------- Starting from 6.3, it is possible to cross-compile Shiboken (module), and -PySide. This functionality is still in Technical Preview, which means it could +PySide. This functionality is still in Technical Preview, which means it could change in the future releases. .. important:: The only supported configuration is using a host Linux @@ -169,7 +177,7 @@ Prerequisites ~~~~~~~~~~~~~ First and foremost, you need to have access to the target device because you -need to copy several system files (sysroot). We recommend a Linux OS that has +need to copy several system files (sysroot). We recommend a Linux OS that has the latest Qt versions, like `Manjaro ARM`_ or `Archlinux ARM`_. * (target) Install Qt 6.3+ on the system using the package manager. @@ -182,7 +190,7 @@ the latest Qt versions, like `Manjaro ARM`_ or `Archlinux ARM`_. After installing these prerequisites, copy the ``target`` sysroot to your ``host`` computer. This process is tricky, because copying system files from -another computer might cause problems with the symbolic links. Here you +another computer might cause problems with the symbolic links. Here you have two options to achieve that. Option A: Copying the files @@ -267,7 +275,7 @@ and unpacked it. With those compilers, now you need a CMake toolchain file. This is a configuration file to set the compilers and sysroot information, together -with extra options like compilation flags, and other details. You can use the +with extra options like compilation flags, and other details. You can use the following file as an example, but keep in mind they might vary: .. code-block:: cmake @@ -408,18 +416,19 @@ You can find the ``requirements-doc.txt`` file in the root of the repository. Starting from 5.15, there are two options to build the documentation: -1. Building rst-only documentation (no API) +1. Building the base documentation (no API) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The process of parsing Qt headers to generate the PySide API documentation can take several -minutes, this means that modifying a specific section of the rst files we currently have, might -become a hard task. +minutes, this means that modifying a specific section of the documentation we currently have, might +become a hard task. You may only care about the base documentation, which comprises all the +documentation except for the API documentation. -For this, you can install :command:`sphinx` on a virtual environment, and execute the following command:: +To generate this, execute the following command:: - python setup.py build_rst_docs + python setup.py build_base_docs -which will generate a ``html/`` directory with the following structure:: +This will generate an ``html/`` directory with the following structure:: html └── pyside6 @@ -435,13 +444,14 @@ files. This is useful when updating the general sections of the documentation, adding tutorials, modifying the build instructions, and more. -.. note:: In case you are interested in generating the Example Gallery, you - would need to first run ``python tools/example_gallery/main.py`` to - generate the examples ``rst`` for the gallery. +.. note:: In case you are interested in only generating the Example Gallery, + you would need to run ``python tools/example_gallery/main.py`` to + generate the examples ``documentation`` for the gallery. This will + also be used internally by the ``build_base_docs`` target -2. Building the documentation (rst + API) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +2. Building the documentation (Base + API) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The documentation is being generated using **qdoc** to get the API information, and also **sphinx** for the local Python related notes. @@ -453,13 +463,11 @@ the ``dot`` command needs to be in PATH, otherwise, the process will fail. Installing ``graphviz`` system-wide is also an option. Since the process relies on a Qt installation, you need to specify where the -``qtbase`` directory of a Qt source tree is located, either by using -the command line option ``--qt-src-dir`` or setting the environment variable:: - - export QT_SRC_DIR=/path/to/qtbase +``qtbase`` directory of a Qt source tree is located by passing it to +the command line option ``--qt-src-dir``. Once the common ``setup.py`` build process finishes (remember to use -``--build-docs`` to enable the documentation build, and ``--doc-build-inline`` +``--build-docs`` to enable the documentation build, and ``--doc-build-online`` to get the HTML files), you can go to the generated ``build/<your_env_name>/build/pyside6`` directory, and run:: @@ -468,9 +476,9 @@ to get the HTML files), you can go to the generated You can add ``-j X``, to perform the build process in parallel with X processes. -.. note:: The :command:`apidoc` make target builds offline documentation in QCH (Qt Creator Help) - format by default. You can switch to building for the online use with the ``--doc-build-online`` - configure option. +.. note:: The :command:`apidoc` make target builds offline documentation in ``QCH`` + (Qt Compressed Help) format by default. You can switch to building for the + online use with the ``--doc-build-online`` configure option. The target executes several steps: @@ -480,7 +488,7 @@ The target executes several steps: Re-running the command will not execute step 1 unless the file ``qdoc-output/webxml/qtcore-index.webxml`` is removed from the build tree. -Similarly, step 2 will not be executed unless the file ``rst/PySide6/QtCore/index.rst`` +Similarly, step 2 will not be executed unless the file ``base/PySide6/QtCore/index.rst`` is removed. Finally, you will get a ``html`` directory containing all the generated documentation. The offline @@ -490,21 +498,32 @@ can find ``Shiboken.qch`` in the build directory, ``build/<your_env_name>/build/ If you want to temporarily change a ``.rst`` file to examine the impact on formatting, you can re-run ``sphinx`` in the ``doc`` directory:: - sphinx-build rst html + sphinx-build base html Viewing offline documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The offline documentation (QCH) can be viewed using the Qt Creator IDE or Qt Assistant, which is -a standalone application for viewing QCH files. +The offline documentation (QCH) can be viewed using the *Qt Creator* IDE or +*Qt Assistant*, which is a standalone application for viewing QCH files. -To view the QCH using Qt Creator, following the instructions outlined in -`Using Qt Creator Help Mode <https://doc.qt.io/qtcreator/creator-help.html>`_. If you chose to -use Qt Assistant instead, use the following command to register the QCH file before launching -Qt Assistant:: +To view the QCH using *Qt Creator*, following the instructions outlined in +`Using Qt Creator Help Mode <https://doc.qt.io/qtcreator/creator-help.html>`_. +If you chose to use *Qt Assistant* instead, use the following command to register +the QCH file before launching *Qt Assistant*:: assistant -register PySide.qch +Troubleshooting documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The documentation uses intersphinx to link from the PySide to the +Shiboken documentation. This can fail if + +* the default ``QCH`` format is used; in which case the required ``objects.inv`` + files are not generated. Use ``--doc-build-online``. +* base and full doc builds are mixed, resulting in wrong values for the + intersphinx location in the CMake files. Re-run ``cmake`` to fix this. + Using the internal tools ------------------------ |