diff options
Diffstat (limited to 'sources/pyside6/doc/gettingstarted/index.rst')
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/index.rst | 159 |
1 files changed, 101 insertions, 58 deletions
diff --git a/sources/pyside6/doc/gettingstarted/index.rst b/sources/pyside6/doc/gettingstarted/index.rst index 36da0bea9..9d36061ad 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.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`_. +* 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,20 +43,44 @@ Guides per platform You can refer to the following pages for platform specific instructions: -.. raw:: html - - <table class="special"> - <colgroup> - <col style="width: 200px" /> - <col style="width: 200px" /> - <col style="width: 200px" /> - </colgroup> - <tr> - <td><a href="gettingstarted-windows.html"><p><strong>Windows</strong></p></a></td> - <td><a href="gettingstarted-macOS.html"><p><strong>macOS</strong></p></a></td> - <td><a href="gettingstarted-linux.html"><p><strong>Linux</strong></p></a></td> - </tr> - </table> +.. grid:: 1 3 3 3 + :gutter: 2 + + .. grid-item-card:: + :img-top: ../images/windows.svg + :class-item: text-center + + +++ + .. button-ref:: windows + :color: primary + :outline: + :expand: + + Windows + + .. grid-item-card:: + :img-top: ../images/macos.svg + :class-item: text-center + + +++ + .. button-ref:: macOS + :color: primary + :outline: + :expand: + + macOS + + .. 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 @@ -78,6 +104,8 @@ 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: * ``--cmake``, to specify the path to the cmake binary, * ``--reuse-build``, to rebuild only the modified files, @@ -115,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 @@ -149,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. @@ -162,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 @@ -247,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 @@ -379,20 +407,28 @@ Starting from 6.3, the documentation is not being built by default. When using the second option described in this section, make sure to use the ``--build-docs`` option. +Install the specific documentation requirements in your Python virtual +environment:: + + pip install -r requirements-doc.txt + +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 @@ -408,35 +444,30 @@ 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. The system requires the ``libxml2`` and ``libxslt`` libraries. -In the Python environment, ``graphviz`` needs to be installed on top -of the modules listed in ``requirements.txt`` before running the -installation process:: - pip install graphviz - -After installing ``graphviz``, the ``dot`` command needs to be in PATH, otherwise, +After installing ``graphviz`` (included in the ``requirements-doc.txt`` file), +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:: @@ -445,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: @@ -457,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 @@ -467,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 ------------------------ @@ -527,3 +569,4 @@ A set of tools can be found under the ``tools/`` directory inside the ``pyside-s .. _repository: https://github.com/liyanage/macosx-shell-scripts/ .. _`wiki page`: https://wiki.qt.io/Qt_for_Python_Missing_Bindings .. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/ +.. _`CMake Unity Build Mode` : https://cmake.org/cmake/help/latest/prop_tgt/UNITY_BUILD.html |