diff options
author | Cristián Maureira-Fredes <cristian.maureira-fredes@qt.io> | 2022-10-27 16:20:52 +0200 |
---|---|---|
committer | Cristián Maureira-Fredes <cristian.maureira-fredes@qt.io> | 2022-11-03 13:48:46 +0100 |
commit | 782acff166d4a2b63846c7ba5493f230cccbd4fc (patch) | |
tree | a213ae7028df42b7d5092b922c79f6a29e6fa017 /sources/pyside6/doc | |
parent | 7fde6c515363864f0f16edd0f447a61369d09935 (diff) |
doc: order the sidebar content
As a quick-access to all the documentation,
the sidebar of the documentation was a mix of topics without
any logical order.
Creating directories with an index.rst file,
and putting the content on the right topic toctree
allow us to have a more clear and simple general toc.
Change-Id: I43af890ce988946ababcd575d431fc66704c3e85
Pick-to: 6.4
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
Diffstat (limited to 'sources/pyside6/doc')
27 files changed, 123 insertions, 114 deletions
diff --git a/sources/pyside6/doc/api.rst b/sources/pyside6/doc/api.rst index eac37a16c..62273c31f 100644 --- a/sources/pyside6/doc/api.rst +++ b/sources/pyside6/doc/api.rst @@ -1,7 +1,7 @@ .. _pyside-api: -|project| Modules -================= +Modules API +=========== Basic modules ------------- @@ -74,4 +74,6 @@ All the modules There are many other modules currently supported by |pymodname|, here you can find a complete list of them. - :doc:`Check all the modules <modules>` +.. toctree:: + + modules.rst diff --git a/sources/pyside6/doc/considerations.rst b/sources/pyside6/doc/considerations.rst index a17cbc269..6f4a059a2 100644 --- a/sources/pyside6/doc/considerations.rst +++ b/sources/pyside6/doc/considerations.rst @@ -1,7 +1,7 @@ .. _pysideapi2: -|project| Considerations -======================== +Considerations +============== API Changes ----------- @@ -149,15 +149,15 @@ There was a long-standing bug in the ``tp_richcompare`` implementation of PySide This oversight was fixed in version 5.15.1 . -|project| Features -================== +Features +-------- In |project|, we begin for the first time to support a more pythonic user interface. With a special import statement, you can switch on features which replace certain aspects of the Python interpreter. This is done by an import statement right after the PySide6 import. snake_case ----------- +~~~~~~~~~~ With the statement: @@ -169,7 +169,7 @@ all methods in the current module are switched from ``camelCase`` to ``snake_cas A single upper case letter is replaced by an underscore and the lower case letter. true_property -------------- +~~~~~~~~~~~~~ With the statement: @@ -182,7 +182,7 @@ are replaced by Python property objects. Properties are also listed as such in the according QMetaObject of a class. Example for both features -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ Some |project| snippet might read: @@ -200,14 +200,14 @@ Additionally, properties can also be declared directly in Shiboken for non Qt-libraries, see :ref:`property-declare`. More about features -------------------- +~~~~~~~~~~~~~~~~~~~ Detailed info about features can be found here: :ref:`feature-why` Tools ------ +~~~~~ -|project| ships some Qt tools: +|project| ships some Qt tools: * ``pyside6-rcc``: Qt Resource Compiler. This is a command line tool that compiles ``.qrc`` files containing binary data, for example images, @@ -227,10 +227,10 @@ Tools .. _NewEnumSystem: The New Python Enums -==================== +-------------------- The Motivation to use new Enums -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For a long time, there were just the Shiboken enums, which were modelled as exact as possible after the existing enums in Qt. These enums are small classes which also inherit from @@ -242,7 +242,7 @@ users. It is therefore just consequent to stop having two different enum impleme in the same application and instead to use the new Python implementation everywhere. Existing Work -------------- +~~~~~~~~~~~~~ The new enums beginning with PySide 6.3, replace the Shiboken enums with Python variants, which harmonize the builtin enums with the already existing @@ -250,7 +250,7 @@ with Python variants, which harmonize the builtin enums with the already existin Activating the New Enums ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ The new approach to enum will be the default in ``PySide 6.4``, but a preview is already built into ``PySide 6.3`` with the environment variable: @@ -263,7 +263,7 @@ reached and a fallback to the old implementation is no longer needed. The Differences between old and new Enums ------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python enums and Shiboken enums are more or less compatible with each other. Tiny differences are in restrictions: @@ -298,7 +298,7 @@ But don't be too scared, here comes the good news... Doing a Smooth Transition from the Old Enums --------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Changing all the enum code to suddenly use the new syntax is cumbersome and error-prone, because such necessary changes are not easy to find. @@ -340,7 +340,7 @@ which don't have a class, see ``Limitations`` below.) Forgiveness Mode and Type Hints -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When you inspect for instance ``QtCore.pyi``, you will only find the new enums, although the old ones are still allowed. Also, line completion will only work with the new constructs @@ -365,8 +365,8 @@ but this construct is used and recommended for the future: self.text.setAlignment(Qt.AlignmentFlag.AlignCenter) -Limitations: ------------- +Limitations +~~~~~~~~~~~ The forgiveness mode works very well whenever the enum class is embedded in a normal PySide class. But there are a few global enums, where especially the ``QtMsgType`` diff --git a/sources/pyside6/doc/contents.rst b/sources/pyside6/doc/contents.rst index 2dbd09997..9d471d7f9 100644 --- a/sources/pyside6/doc/contents.rst +++ b/sources/pyside6/doc/contents.rst @@ -1,19 +1,19 @@ -|project| Documentation -*************************** +.. items for the main front page grid .. toctree:: :maxdepth: 2 quickstart.rst - gettingstarted.rst - porting_from2.rst + gettingstarted/index.rst api.rst tutorials/index.rst examples/index.rst videos.rst - deployment.rst - modules.rst + deployment/index.rst considerations.rst + developer/index.rst + commercial.rst + .. Intersphinx references in toctrees is not supported https://github.com/sphinx-doc/sphinx/issues/1836 diff --git a/sources/pyside6/doc/deployment-briefcase.rst b/sources/pyside6/doc/deployment/deployment-briefcase.rst index 95aee1432..95aee1432 100644 --- a/sources/pyside6/doc/deployment-briefcase.rst +++ b/sources/pyside6/doc/deployment/deployment-briefcase.rst diff --git a/sources/pyside6/doc/deployment-cxfreeze.rst b/sources/pyside6/doc/deployment/deployment-cxfreeze.rst index 681dcf315..681dcf315 100644 --- a/sources/pyside6/doc/deployment-cxfreeze.rst +++ b/sources/pyside6/doc/deployment/deployment-cxfreeze.rst diff --git a/sources/pyside6/doc/deployment-fbs.rst b/sources/pyside6/doc/deployment/deployment-fbs.rst index c2a2397d2..c2a2397d2 100644 --- a/sources/pyside6/doc/deployment-fbs.rst +++ b/sources/pyside6/doc/deployment/deployment-fbs.rst diff --git a/sources/pyside6/doc/deployment-nuitka.rst b/sources/pyside6/doc/deployment/deployment-nuitka.rst index 9be982a4c..9be982a4c 100644 --- a/sources/pyside6/doc/deployment-nuitka.rst +++ b/sources/pyside6/doc/deployment/deployment-nuitka.rst diff --git a/sources/pyside6/doc/deployment-py2exe.rst b/sources/pyside6/doc/deployment/deployment-py2exe.rst index 24d260d71..24d260d71 100644 --- a/sources/pyside6/doc/deployment-py2exe.rst +++ b/sources/pyside6/doc/deployment/deployment-py2exe.rst diff --git a/sources/pyside6/doc/deployment-pyinstaller.rst b/sources/pyside6/doc/deployment/deployment-pyinstaller.rst index eb900bd74..eb900bd74 100644 --- a/sources/pyside6/doc/deployment-pyinstaller.rst +++ b/sources/pyside6/doc/deployment/deployment-pyinstaller.rst diff --git a/sources/pyside6/doc/deployment.rst b/sources/pyside6/doc/deployment/index.rst index 69b4b7d96..98b80500b 100644 --- a/sources/pyside6/doc/deployment.rst +++ b/sources/pyside6/doc/deployment/index.rst @@ -1,7 +1,7 @@ .. _deployment-guides: -|project| Deployment -==================== +Deployment +========== Deploying or freezing an application is an important part of a Python project, this means to bundle all required resources so that the application finds everything it needs to diff --git a/sources/pyside6/doc/developer/enumfeatures_doc.rst b/sources/pyside6/doc/developer/enumfeatures_doc.rst index 63535d5f2..b3edbe7b6 100644 --- a/sources/pyside6/doc/developer/enumfeatures_doc.rst +++ b/sources/pyside6/doc/developer/enumfeatures_doc.rst @@ -1,6 +1,5 @@ -************************ The Set of Enum Features -************************ +======================== The development of the new Python enums took the form of a series of patches. While we put a lot of effort into supporting the old Enums (without promoting @@ -11,7 +10,7 @@ combination of enum functions step by step with a specific set of flags. The Possible Enum Flags -======================= +----------------------- This is the table of all flags used to control the creation of Python enums. @@ -37,7 +36,7 @@ by using ``ast.literal_eval``. ENOPT_OLD_ENUM (0x00) ---------------------- +~~~~~~~~~~~~~~~~~~~~~ This option completely disables the new enum implementation. Even though this is a valid option, we want to avoid it if possible. @@ -48,7 +47,7 @@ to provide a temporary solution before extending enum support accordingly. ENOPT_NEW_ENUM (0x01) ---------------------- +~~~~~~~~~~~~~~~~~~~~~ In a perfect world, no one would choose anything other than this default setting. Unfortunately, reality is not always like that. That is why @@ -56,7 +55,7 @@ there are the following flags. The most likely flags needed -============================ +---------------------------- If there are errors, they are likely to be the following: Either implicit assumptions are there that require IntEnum, or global enums are used that @@ -64,7 +63,7 @@ unfortunately cannot be replaced with tricks. ENOPT_INHERIT_INT (0x02) ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ When this flag is set, all ``enum.Enum/enum.Flag`` classes are converted to ``enum.IntEnum/enum.IntFlag``. This solves the most likely compatibility @@ -84,7 +83,7 @@ workaround until we have implemented alternatives. ENOPT_GLOBAL_SHORTCUT (0x04) ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At the beginning of the Python enum implementation, we continued to support the shortcut behavior of Shiboken enums: the enum constants were mirrored @@ -101,7 +100,7 @@ A flag value of 0x6 is likely to solve the majority of problems. Flags for completeness -====================== +---------------------- The following flags complement the description of Python Enums. They essentially serve the better understanding of the @@ -109,7 +108,7 @@ implementation and make it fully transparent and customizable. ENOPT_SCOPED_SHORTCUT (0x08) ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For completeness, we also supported mirroring scoped enums, although this has since been replaced by forgiveness mode. If you want to try this, @@ -118,7 +117,7 @@ effect of this flag will remain invisible. ENOPT_NO_FAKERENAMES (0x10) ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Forgiveness mode emulates renaming ``Enum.Flag`` classes back to Shiboken QFlags structures, which have slightly different names. @@ -130,7 +129,7 @@ To see the effect of this renaming, you can turn it off with this flag. ENOPT_NO_ZERODEFAULT (0x40) ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ As part of the forgiveness mode, Python enums can be created by a parameterless call, although Python enums actually force a parameter @@ -140,7 +139,7 @@ The effect can be examined if this flag is set to disable it. ENOPT_NO_MISSING (0x80) ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ There are a few cases where Shiboken enums use missing values. In ``enum.Flag`` structures, this is allowed anyway because we have set the diff --git a/sources/pyside6/doc/feature-why.rst b/sources/pyside6/doc/developer/feature-motivation.rst index 33bcf1651..33bcf1651 100644 --- a/sources/pyside6/doc/feature-why.rst +++ b/sources/pyside6/doc/developer/feature-motivation.rst diff --git a/sources/pyside6/doc/developer/index.rst b/sources/pyside6/doc/developer/index.rst index 4c07d1350..23bd21681 100644 --- a/sources/pyside6/doc/developer/index.rst +++ b/sources/pyside6/doc/developer/index.rst @@ -30,3 +30,4 @@ many features and implementation details that the project has: enumfeatures_doc.rst limited_api.rst signature_doc.rst + feature-motivation.rst diff --git a/sources/pyside6/doc/developer/limited_api.rst b/sources/pyside6/doc/developer/limited_api.rst index 3144114a8..44d3faad2 100644 --- a/sources/pyside6/doc/developer/limited_api.rst +++ b/sources/pyside6/doc/developer/limited_api.rst @@ -1,10 +1,9 @@ -************************************************* The Transition To The Limited Python API (PEP384) -************************************************* +================================================= Foreword -======== +-------- Python supports a limited API that restricts access to certain structures. Besides eliminating whole modules and all functions and macros which names @@ -21,7 +20,7 @@ For details about the eliminated modules and functions, please see the Changed Modules -=============== +--------------- All changed module's include files are listed with the changed functions here. As a general rule, it was tried to keep the changes to a minimum diff. @@ -30,7 +29,7 @@ if possible. Completely removed names ``Py{name}`` were re-implemented as ``Pep{ memoryobject.h --------------- +~~~~~~~~~~~~~~ The buffer protocol was completely removed. We redefined all the structures and methods, because PySide uses that. This is an exception to the limited API @@ -39,7 +38,7 @@ This is related to the following: abstract.h ----------- +~~~~~~~~~~ This belongs to the buffer protocol like memoryobject.h . As replacement for ``Py_buffer`` we defined ``Pep_buffer`` and several other @@ -54,14 +53,14 @@ or if we should try to get rid of ``Pep_buffer``, completely. pydebug.h ---------- +~~~~~~~~~ We have no direct access to ``Py_VerboseFlag`` because debugging is not supported. We redefined it as macro ``Py_VerboseFlag`` which calls ``Pep_VerboseFlag``. unicodeobject.h ---------------- +~~~~~~~~~~~~~~~ The macro ``PyUnicode_GET_SIZE`` was removed and replaced by ``PepUnicode_GetLength`` which evaluates to ``PyUnicode_GetSize`` for Python 2 and ``PyUnicode_GetLength`` for Python 3. @@ -73,34 +72,34 @@ and it would be better to change the code and replace this function. bytesobject.h -------------- +~~~~~~~~~~~~~ The macros ``PyBytes_AS_STRING`` and ``PyBytes_GET_SIZE`` were redefined to call the according functions. floatobject.h -------------- +~~~~~~~~~~~~~ ``PyFloat_AS_DOUBLE`` now calls ``PyFloat_AsDouble``. tupleobject.h -------------- +~~~~~~~~~~~~~ ``PyTuple_GET_ITEM``, ``PyTuple_SET_ITEM`` and ``PyTuple_GET_SIZE`` were redefined as function calls. listobject.h ------------- +~~~~~~~~~~~~ ``PyList_GET_ITEM``, ``PyList_SET_ITEM`` and ``PyList_GET_SIZE`` were redefined as function calls. dictobject.h ------------- +~~~~~~~~~~~~ ``PyDict_GetItem`` also exists in a ``PyDict_GetItemWithError`` version that does not suppress errors. This suppression has the side effect of touching global @@ -110,7 +109,7 @@ Needed to avoid the GIL when accessing dictionaries. methodobject.h --------------- +~~~~~~~~~~~~~~ ``PyCFunction_GET_FUNCTION``, ``PyCFunction_GET_SELF`` and ``PyCFunction_GET_FLAGS`` were redefined as function calls. @@ -120,14 +119,14 @@ Direct access to the methoddef structure is not available, and we defined pythonrun.h ------------ +~~~~~~~~~~~ The simple function ``PyRun_String`` is not available. It was re-implemented in a simplified version for the signature module. funcobject.h ------------- +~~~~~~~~~~~~ The definitions of funcobject.h are completely missing, although there are extra ``#ifdef`` conditional defines inside, too. This suggests that the exclusion @@ -145,7 +144,7 @@ There is no equivalent for function name access, therefore we introduced classobject.h -------------- +~~~~~~~~~~~~~ Classobject is also completely not imported, instead of defining an opaque type. @@ -157,7 +156,7 @@ We defined the missing functions ``PyMethod_New``, ``PyMethod_Function`` and code.h ------- +~~~~~~ The whole code.c code is gone, although it may make sense to define some minimum accessibility. This will be clarified on @@ -173,7 +172,7 @@ We further added the missing flags, although few are used: .. _`Python-Dev`: https://mail.python.org/mailman/listinfo/python-dev datetime.h ----------- +~~~~~~~~~~ The DateTime module is explicitly not included in the limited API. We defined all the needed functions but called them via Python instead @@ -211,7 +210,7 @@ The re-defined macros and methods are:: object.h --------- +~~~~~~~~ The file object.h contains the ``PyTypeObject`` structure, which is supposed to be completely opaque. All access to types should be done through @@ -294,7 +293,7 @@ Therefore, a forgotten debugging call of this functions will break COIN. :-) Using The New Type API -====================== +---------------------- After converting everything but the object.h file, we were a little bit shocked: it suddenly was clear that we would have no more @@ -310,7 +309,7 @@ between the APIs and their consequences. The Interface -------------- +~~~~~~~~~~~~~ The old type API of Python knows static types and heap types. Static types are written down as a declaration of a ``PyTypeObject`` @@ -466,7 +465,7 @@ very important, since all derived types invisibly inherit these two fields. Future Versions Of The Limited API -================================== +---------------------------------- As we have seen, the current version of the limited API does a bit of cheating, because it uses parts of the data structure that should be @@ -486,7 +485,7 @@ calls to ``PyType_GetSlot``. After that, no more changes will be necessary. Appendix A: The Transition To Simpler Types -=========================================== +------------------------------------------- After all code had been converted to the limited API, there was a remaining problem with the ``PyHeapTypeObject``. @@ -500,7 +499,7 @@ by a pointer that is computed at runtime. Restricted PyTypeObject ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ Before we are going into details, let us motivate the existence of the restricted ``PyTypeObject``: @@ -539,7 +538,7 @@ explicitly because that *does* change its layout over time. Diversification ---------------- +~~~~~~~~~~~~~~~ There were multiple ``Sbk{something}`` structures which all used a "d" field for their private data. This made it not easy to find the right @@ -573,7 +572,7 @@ After renaming, it was easier to do the following transformations. Abstraction ------------ +~~~~~~~~~~~ After renaming the type extension pointers to ``sotp``, I replaced them by function-like macros which did the special access *behind* @@ -603,7 +602,7 @@ key to fulfil what Pep 384 wants to achieve: *No more version-dependent fields*. Simplification --------------- +~~~~~~~~~~~~~~ After all type extension fields were replaced by macro calls, we could remove the following version dependent re-definition of ``PyHeapTypeObject`` @@ -629,7 +628,7 @@ type alias to PyTypeObject. Appendix B: Verification Of PyTypeObject -======================================== +---------------------------------------- We have introduced a limited PyTypeObject in the same place as the original PyTypeObject, and now we need to prove that @@ -644,7 +643,7 @@ and produces a regular heap type object. Unused Information ------------------- +~~~~~~~~~~~~~~~~~~ We know many things about types that are not explicitly said, but they are inherently clear: @@ -663,7 +662,7 @@ The validation checks if rule (b) is still valid. How it Works ------------- +~~~~~~~~~~~~ The basic idea of the validation is to produce a new type using ``PyType_FromSpec`` and to see where in the type structure these fields @@ -690,7 +689,7 @@ the places where we expect them, then verification is done. About ``tp_dict`` ------------------ +~~~~~~~~~~~~~~~~~ One word about the ``tp_dict`` field: This field is a bit special in the proof, since it does not appear in the spec and cannot easily diff --git a/sources/pyside6/doc/developer/signature_doc.rst b/sources/pyside6/doc/developer/signature_doc.rst index 661cbddce..3bd28ad68 100644 --- a/sources/pyside6/doc/developer/signature_doc.rst +++ b/sources/pyside6/doc/developer/signature_doc.rst @@ -1,6 +1,7 @@ -************************* +.. _signature-extension: + The signature C extension -************************* +========================= This module is a C extension for CPython 3.5 and up, and CPython 2.7. Its purpose is to provide support for the ``__signature__`` attribute @@ -8,7 +9,7 @@ of builtin PyCFunction objects. Short Introduction to the Topic -=============================== +------------------------------- Beginning with CPython 3.5, Python functions began to grow a ``__signature__`` attribute for normal Python functions. This is totally optional and just @@ -20,7 +21,7 @@ would be nice to have this info directly available. The Idea to Support Signatures -============================== +------------------------------ We want to have an additional ``__signature__`` attribute in all PySide methods, without changing lots of generated code. @@ -35,7 +36,7 @@ this is an adequate compromise. How this Code Works -------------------- +~~~~~~~~~~~~~~~~~~~ Signatures are supported for regular Python functions, only. Creating signatures for ``PyCFunction`` objects would require quite some extra effort in Python. @@ -71,7 +72,7 @@ It calls ``GetSignature_Function`` which returns the signature if it is found. Why this Code is Fast ---------------------- +~~~~~~~~~~~~~~~~~~~~~ It costs a little time (maybe 6 seconds) to run through every single signature object, since these are more than 25000 Python objects. But all the signature @@ -103,7 +104,7 @@ It turned out that the overhead is below 0.5 ms. The Signature Package Structure -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The C++ code involved with the signature module is completely in the file shiboken6/libshiboken/signature.cpp . All other functionality is implemented in @@ -136,7 +137,7 @@ or be compatible with embedding and installers. loader.py -~~~~~~~~~ ++++++++++ This module assembles and imports the ``inspect`` module, and then exports the ``create_signature`` function. This function takes a fake function and some @@ -144,7 +145,7 @@ attributes and builds a ``__signature__`` object with the inspect module. parser.py -~~~~~~~~~ ++++++++++ This module takes a class signatures string from C++ and parses it into the needed properties for the ``create_signature`` function. Its entry point is the @@ -152,7 +153,7 @@ needed properties for the ``create_signature`` function. Its entry point is the mapping.py -~~~~~~~~~~ +++++++++++ The purpose of the mapping module is maintaining a list of replacement strings that map from the *signature text* in C to the property strings that Python @@ -161,7 +162,7 @@ but a few hundred cases are better to spell explicitly, here. errorhandler.py -~~~~~~~~~~~~~~~ ++++++++++++++++ Since ``Qt For Python 5.12``, we no longer use the builtin type error messages from C++. Instead, we get much better results with the signature module. At the same time, @@ -170,7 +171,7 @@ optional. enum_sig.py -~~~~~~~~~~~ ++++++++++++ The diverse applications of the signature module all needed to iterate over modules, classes and functions. In order to centralize this enumeration, the process has @@ -181,7 +182,7 @@ See for example the .pyi generator ``pyside6/PySide6/support/generate_pyi.py``. layout.py -~~~~~~~~~ ++++++++++ As more applications used the signature module, different formatting of signatures was needed. To support that, we created the function ``create_signature``, which @@ -189,13 +190,13 @@ has a parameter to choose from some predefined layouts. *typing27.py* -~~~~~~~~~~~~~ ++++++++++++++ Python 2 has no typing module at all. This is a backport of the minimum that is needed. *backport_inspect.py* -~~~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++++ Python 2 has an inspect module, but lacks the signature functions, completely. This module adds the missing functionality, which is merged at runtime into @@ -203,7 +204,7 @@ the inspect module. Multiple Arities ----------------- +~~~~~~~~~~~~~~~~ One aspect that was ignored so far was *multiple arities*: How to handle it when a function has more than one signature? @@ -216,7 +217,7 @@ but this simple rules seem to work well: Impacts of The Signature Module -=============================== +------------------------------- The signature module has a number of impacts to other PySide modules, which were created as a consequence of its existence, and there will be a few more in the @@ -224,7 +225,7 @@ future: existence_test.py ------------------ +~~~~~~~~~~~~~~~~~ The file ``pyside6/tests/registry/existence_test.py`` was written using the signatures from the signatures module. The idea is that there are some 15000 @@ -241,7 +242,7 @@ An error is normally only reported as a warning, but: Interaction With The Coin Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++++++ When this test program is run in COIN, then the warnings are turned into errors. The reason is that only in COIN, we have a stable configuration @@ -252,7 +253,7 @@ exception for generated code, these files are *intentionally* checked in. What Happens When a List is Missing? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +++++++++++++++++++++++++++++++++++++ When a new version of PySide gets created, then the existence test files initially do not exist. @@ -271,7 +272,7 @@ in. Explicitly Enforcing Recreation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++++++++++++++++++++++++++++++++ The former way to regenerate the registry files was to remove the files and check that in. This has the desired effect, but creates huge deltas. @@ -282,7 +283,7 @@ effect. init_platform.py -~~~~~~~~~~~~~~~~ +++++++++++++++++ For generating the ``exists_{platf}_{version}`` modules, the module ``pyside6/tests/registry/init_platform.py`` was written. It can be used @@ -291,7 +292,7 @@ changes, directly. scrape_testresults.py ---------------------- +~~~~~~~~~~~~~~~~~~~~~ To simplify and automate the process of extracting the ``exists_{platf}_{version}_ci.py`` files, the script ``pyside6/tests/registry/scrape_testresults.py`` has been written. @@ -317,7 +318,7 @@ folder. It should be reviewed and then eventually checked in. generate_pyi.py ---------------- +~~~~~~~~~~~~~~~ ``pyside6/PySide6/support/generate_pyi.py`` is still under development. This module generates so-called hinting stubs for integration of PySide @@ -342,7 +343,7 @@ A useful command to change all .pyi files to use all features is pyi_generator.py ----------------- +~~~~~~~~~~~~~~~~ ``shiboken6/shibokenmodule/files.dir/shibokensupport/signature/lib/pyi_generator.py`` has been extracted from ``generate_pyi.py``. It allows the generation of ``.pyi`` @@ -352,7 +353,7 @@ A shortcut for this command is ``shiboken6-genpyi``. Current Extensions ------------------- +~~~~~~~~~~~~~~~~~~ Before the signature module was written, there already existed the concept of signatures, but in a more C++ - centric way. From that time, there existed @@ -369,7 +370,7 @@ This was implemented in ``Qt For Python 5.12.1``. Literature -========== +---------- `PEP 362 – Function Signature Object <https://www.python.org/dev/peps/pep-0362/>`__ diff --git a/sources/pyside6/doc/gettingstarted.rst b/sources/pyside6/doc/gettingstarted/index.rst index ae97c885b..814a9c48e 100644 --- a/sources/pyside6/doc/gettingstarted.rst +++ b/sources/pyside6/doc/gettingstarted/index.rst @@ -1,5 +1,5 @@ -|project| Getting Started -========================== +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`. @@ -29,6 +29,16 @@ website. Guides per platform ------------------- +.. toctree:: + :maxdepth: 1 + :hidden: + + linux.rst + macOS.rst + windows.rst + package_details.rst + porting_from2.rst + You can refer to the following pages for platform specific instructions: .. raw:: html diff --git a/sources/pyside6/doc/gettingstarted-linux.rst b/sources/pyside6/doc/gettingstarted/linux.rst index 7d4000da2..7d4000da2 100644 --- a/sources/pyside6/doc/gettingstarted-linux.rst +++ b/sources/pyside6/doc/gettingstarted/linux.rst diff --git a/sources/pyside6/doc/gettingstarted-macOS.rst b/sources/pyside6/doc/gettingstarted/macOS.rst index 7c3784b02..7c3784b02 100644 --- a/sources/pyside6/doc/gettingstarted-macOS.rst +++ b/sources/pyside6/doc/gettingstarted/macOS.rst diff --git a/sources/pyside6/doc/package_details.rst b/sources/pyside6/doc/gettingstarted/package_details.rst index 576ff0d47..576ff0d47 100644 --- a/sources/pyside6/doc/package_details.rst +++ b/sources/pyside6/doc/gettingstarted/package_details.rst diff --git a/sources/pyside6/doc/packages.png b/sources/pyside6/doc/gettingstarted/packages.png Binary files differindex 57e7ca47d..57e7ca47d 100644 --- a/sources/pyside6/doc/packages.png +++ b/sources/pyside6/doc/gettingstarted/packages.png diff --git a/sources/pyside6/doc/porting_from2.rst b/sources/pyside6/doc/gettingstarted/porting_from2.rst index 2d5c8414f..2d5c8414f 100644 --- a/sources/pyside6/doc/porting_from2.rst +++ b/sources/pyside6/doc/gettingstarted/porting_from2.rst diff --git a/sources/pyside6/doc/gettingstarted-windows.rst b/sources/pyside6/doc/gettingstarted/windows.rst index 5fec92bca..5fec92bca 100644 --- a/sources/pyside6/doc/gettingstarted-windows.rst +++ b/sources/pyside6/doc/gettingstarted/windows.rst diff --git a/sources/pyside6/doc/index.rst b/sources/pyside6/doc/index.rst index 73650bb73..6a0ec4d99 100644 --- a/sources/pyside6/doc/index.rst +++ b/sources/pyside6/doc/index.rst @@ -179,6 +179,3 @@ We have also a `wiki page`_ where you can find how to report bugs, contribute or :glob: contents.rst - gettingstarted* - overviews/* - feature-why diff --git a/sources/pyside6/doc/quickstart.rst b/sources/pyside6/doc/quickstart.rst index d6f83a383..75e923e4d 100644 --- a/sources/pyside6/doc/quickstart.rst +++ b/sources/pyside6/doc/quickstart.rst @@ -1,5 +1,5 @@ -|project| Quick start -====================== +Quick start +=========== Requirements ------------ diff --git a/sources/pyside6/doc/tutorials/index.rst b/sources/pyside6/doc/tutorials/index.rst index ae29da9d9..653bc19ab 100644 --- a/sources/pyside6/doc/tutorials/index.rst +++ b/sources/pyside6/doc/tutorials/index.rst @@ -1,5 +1,5 @@ -|project| Tutorials -==================== +Tutorials +========= A collection of tutorials with walkthrough guides are provided with |project| to help new users get started. diff --git a/sources/pyside6/doc/tutorials/portingguide/index.rst b/sources/pyside6/doc/tutorials/portingguide/index.rst index ed1a7a4f6..dc84b0c05 100644 --- a/sources/pyside6/doc/tutorials/portingguide/index.rst +++ b/sources/pyside6/doc/tutorials/portingguide/index.rst @@ -8,7 +8,7 @@ to Python to understand this. Before you start, ensure that all the prerequisites for Qt for Python are met. See -:doc:`Getting Started <../../gettingstarted>` for more +:doc:`Getting Started <../../gettingstarted/index>` for more information. In addition, familiarize yourself with the basic differences between Qt in C++ and in Python. diff --git a/sources/pyside6/doc/videos.rst b/sources/pyside6/doc/videos.rst index ea5c3bc6d..bd2ee60af 100644 --- a/sources/pyside6/doc/videos.rst +++ b/sources/pyside6/doc/videos.rst @@ -1,7 +1,7 @@ .. _video-gallery: -|project| Videos -================ +Videos +====== Tutorials --------- |