diff options
Diffstat (limited to 'sources/pyside2/doc/gettingstarted.rst')
| -rw-r--r-- | sources/pyside2/doc/gettingstarted.rst | 257 |
1 files changed, 180 insertions, 77 deletions
diff --git a/sources/pyside2/doc/gettingstarted.rst b/sources/pyside2/doc/gettingstarted.rst index 0ee6a9173..1623538cf 100644 --- a/sources/pyside2/doc/gettingstarted.rst +++ b/sources/pyside2/doc/gettingstarted.rst @@ -1,115 +1,218 @@ -=============== -Getting Started -=============== +|project| Getting Started +========================== -To develop with |project|, you must install Python, Clang, and |project|. +This page is focused on building |project| from source, if you just want to install |pymodname| +with ``pip`` you need to run:: -Preparing for the Installation -============================== + pip install pyside2 -Before you can install |project|, you must install the following software: +for more details, refer to our `Quick Start`_ guide. Additionally, you can +check the :ref:`FAQ <faq>` related to the project. -* Python 3.5+ or 2.7 -* libclang 5.0+ (for Qt 5.11) or 6.0+ (for Qt 5.12) -* Recommended: a virtual environment, such as `venv <https://docs.python.org/3/library/venv.html>`_ or `virtualenv <https://virtualenv.pypa.io/en/stable/installation>`_ +.. _Quick Start: quickstart.html -Installing |project| -==================== +General Requirements +-------------------- -After you have installed the required software, you are ready to install the |project| -packages using the pip wheel. Run the following command from your command -prompt to install:: + * **Python**: 3.5+ and 2.7 + * **Qt:** 5.12+ is recommended + * **libclang:** The libclang library, recommended: version 10 for PySide2 5.15. + Prebuilt versions of it can be `downloaded here`_. + * **CMake:** 3.1+ is needed. - pip install PySide2 # For the latest version on PyPi +.. _downloaded here: http://download.qt.io/development_releases/prebuilt/libclang/ -or:: +Guides per platform +------------------- - pip install --index-url=http://download.qt.io/snapshots/ci/pyside/5.12/latest pyside2 --trusted-host download.qt.io +You can refer to the following pages for platform specific instructions: -Testing the Installation -======================== + * `Windows`_ + * `macOS`_ + * `Linux`_ + * Mobile platforms (iOS/Android) **(no support)** + * Embedded platforms **(no official support)** -Now that you have |project| installed, you can test your setup by running the following Python -constructs to print version information:: + .. note:: Most Linux-based embedded OS provide PySide2 with their official + package manager (e.g. `Raspbian`_ and `ArchlinuxARM`_). - import PySide2.QtCore +.. _Windows: gettingstarted-windows.html +.. _macOS: gettingstarted-macOS.html +.. _Linux: gettingstarted-linux.html +.. _Raspbian: https://www.raspbian.org/ +.. _ArchlinuxARM: https://archlinuxarm.org/ - # Prints PySide2 version - # e.g. 5.11.1a1 - print(PySide2.__version__) +A normal building command will look like this:: - # Gets a tuple with each version component - # e.g. (5, 11, 1, 'a', 1) - print(PySide2.__version_info__) + python setup.py install --qmake=/path/to/qmake \ + --ignore-git \ + --debug \ + --build-tests \ + --parallel=8 \ + --make-spec=ninja \ + --verbose-build \ + --module-subset=Core,Gui,Widgets - # Prints the Qt version used to compile PySide2 - # e.g. "5.11.2" - print(PySide2.QtCore.__version__) +Which will build and install the project with **debug** symbols, including the **tests**, +using **ninja** (instead of make), and considering only the **module subset** of QtCore, QtGUI +and QtWidgets. - # Gets a tuple with each version components of Qt used to compile PySide2 - # e.g. (5, 11, 2) - print(PySide2.QtCore.__version_info__) +Other important options to consider are: + * ``--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, + * ``--standalone``, to copy over the Qt libraries into the final package + to make it work on other machines, + * ``--doc-build-online``, to build documentation using the online template. -Creating a Simple Application -============================= +Testing the installation +------------------------ -Your |project| setup is ready, so try exploring it further by developing a simple application -that prints "Hello World" in several languages. The following instructions will -guide you through the development process: +Once the installation finishes, you will be able to execute any of our examples:: -* Create a new file named :code:`hello_world.py`, and add the following imports to it. + python examples/widgets/widgets/tetrix.py - :: +Running Tests +------------- - import sys - import random - from PySide2 import QtCore, QtWidgets, QtGui +Using the ``--build-tests`` option will enable us to run all the auto tests inside the project:: - The |pymodname| Python module provides access to the Qt APIs as its submodule. - In this case, you are importing the :code:`QtCore`, :code:`QtWidgets`, and :code:`QtGui` submodules. + python testrunner.py test > testlog.txt -* Define a class named :code:`MyWidget`, which extends QWidget and includes a QPushButton and QLabel. +.. note:: On Windows, don't forget to have qmake in your path + (``set PATH=E:\Path\to\Qt\5.15\msvc2017_64\bin;%PATH%``) - :: +You can also run a specific test (for example ``qpainter_test``) by running:: - class MyWidget(QtWidgets.QWidget): - def __init__(self): - super().__init__() + ctest -R qpainter_test --verbose - self.hello = ["Hallo Welt", "Hei maailma", "Hola Mundo", "Привет мир"] +Building the documentation +-------------------------- - self.button = QtWidgets.QPushButton("Click me!") - self.text = QtWidgets.QLabel("Hello World") - self.text.setAlignment(QtCore.Qt.AlignCenter) +Starting from 5.15, there are two options to build the documentation: - self.layout = QtWidgets.QVBoxLayout() - self.layout.addWidget(self.text) - self.layout.addWidget(self.button) - self.setLayout(self.layout) +1. Building rst-only documentation (no API) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - self.button.clicked.connect(self.magic) +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. +For this, you can install ``sphinx`` on a virtual environment, and execute the following command:: - def magic(self): - self.text.setText(random.choice(self.hello)) + python setup.py build_rst_docs - The MyWidget class has the :code:`magic` member function that - randomly chooses an item from the list :code:`hello`. This function - is called when you click the button. +which will generate a ``html/`` directory with the following structure:: -* Now, add a main function where you instantiate :code:`MyWidget` and - :code:`show` it. + html + └── pyside2 + ├── index.html + ├── ... + └── shiboken2 + ├── index.html + └── ... - :: +so you can open the main page ``html/pyside2/index.html`` on your browser to check the generated +files. - if __name__ == "__main__": - app = QtWidgets.QApplication([]) +This is useful when updating the general sections of the documentation, adding tutorials, +modifying the build instructions, and more. - widget = MyWidget() - widget.resize(800, 600) - widget.show() +2. Building the documentation (rst + API) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - sys.exit(app.exec_()) +The documentation is being generated using **qdoc** to get the API information, and also **sphinx** +for the local Python related notes. -Your example is ready to be run. Try clicking the button at the bottom -and see which greeting you get. +The system required ``libxml2`` and ``libxslt``, also on the Python environment, ``sphinx`` and +``graphviz`` need to be installed before running the installation process:: + + pip install graphviz sphinx + +After installing ``graphviz``, the ``dot`` command needs to be in PATH, otherwise, +the process will fail. Installing ``graphviz`` system-wide is also an option. + +Since the process rely on a Qt installation, you need to specify where the ``qtbase`` directory +you will use with your ``qmake`` is located:: + + export QT_SRC_DIR=/path/to/qtbase + +Once the build process finishes, you can go to the generated ``*_build/*_release/pyside2`` +directory, and run:: + + make apidoc + +.. note:: The ``apidoc`` make target builds offline documenation in QCH (Qt Creator Help) format + by default. You can switch to building for the online use with the ``--doc-build-online`` + configure option. + +Finally, you will get a ``html`` directory containing all the generated documentation. The offline +help files, ``PySide.qch`` and ``Shiboken.qch``, can be moved to any directory of your choice. You +can find ``Shiboken.qch`` in the build directory, ``*_build\*_release\shiboken2\doc\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. + +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 + +.. note:: Qt Assistant renders the QCH content using the QTextBrowser backend, which supports + a subset of the CSS styles, However, Qt Creator offers an alternative litehtml-based + backend, which offers better browsing experience. At the moment, this is not the default + backend, so you have to select the litehtml backend + explicitly under the ``General`` tab in ``Qt Creator >> Tools >> Options >> Help``. + +Using the internal tools +------------------------ + +A set of tools can be found under the ``tools/`` directory inside the ``pyside-setup`` repository. + +* ``checklibs.py``: Script to analyze dynamic library dependencies of Mach-O binaries. + To use this utility, just run:: + + python checklibs.py /path/to/some.app/Contents/MacOS/Some + + This script was fetched from this repository_. + +* ``create_changelog.py``: Script used to create the CHANGELOG that you can find in the ``dist/`` + directory. Usage:: + + python create_changelog.py -r 5.15.1 -v v5.15.0..5.15 -t bug-fix + +* ``debug_windows.py``: This script can be used to find out why PySide2 modules + fail to load with various DLL errors like Missing DLL or Missing symbol in DLL. + + You can think of it as a Windows version of ``ldd`` / ``LD_DEBUG``. + + Underneath it uses the ``cdb.exe`` command line debugger, and the ``gflags.exe`` tool, both + installed with the latest Windows Kit. + + The aim is to ask users to run this script when they encounter PySide2 imports not working on + Windows. The user should then provide the generated log file. + + Incidentally it can also be used for any Windows executables, not just Python. + To use it just run:: + + python debug_windows.py + +* ``missing_bindings.py``: This script is used to compare the state of PySide2 and PyQt5 + regarding available modules and classses. This content is displayed in our `wiki page`_, + and can be used as follows:: + + python missing_bindings.py --qt-version 5.15.1 -w all + + Please keep in mind we rely on BeautifulSoup_ to parse the content, so you will be to install + it besides PySide2 and PyQt5 (Including additional modules like DataVisualiztion, QtCharts, + WebEngine, etc). + + +.. _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/ |