PyQtDocs - The PyQt Documentation
=================================

The PyQt documentation is created from four sources:

- the fixed documentation found in the ``docs`` directory
- the .sip files for the version of PyQt being documented
- the Qt source code containing the documentation of the C++ API
- handwritten ports to Python of the Qt documentation (in the ``descriptions``
  directory) and code snippets (in the ``snippets`` directory).

The system is designed so that it can be safely re-based for new versions of
PyQt and Qt (separately and together) without losing any of the handwritten
ports.


Building the HTML Documentation
-------------------------------

To build the HTML documentation, run the following command::

    sphinx-build docs html

The documentation can be found in the ``html`` directory.


Re-basing for New Versions of PyQt
----------------------------------

The ``conf.py`` file in the ``docs`` directory should be updated with the
X.Y.Z version number of the new PyQt version.

For each PyQt module (e.g. QtCore), run the following command::

    python sip2rst.py --package PyQt5 module

This will update the files in the ``api`` sub-directory of the ``docs``
directory.

The above command assumes that the PyQt .sip files have been installed in their
default location and that the ``sip`` executable is on ``PATH``.
``sip2rst.py`` has command line options to override the default locations if
necessary.


Re-basing for New Versions of Qt
--------------------------------

To update the descriptions of the PyQt API in the ``descriptions`` directory
for a new version of Qt, run the following command::

    python webxml2rst.py --package PyQt5 --qdoc QDOC --qt-source SRC

``QDOC`` is the pathname of the ``qdoc`` executable.

``SRC`` is the name of the directory containing the Qt source code.

This will *not* overwrite any hand-written changes to the descriptions.

This will also update any code snippets and images for updated descriptions.


Updating the Code Snippets
--------------------------

The ``snippets`` directory contains Python code snippets that are initially
created from the original C++ code snippets by converting each line to a Python
comment.

The snippets are included in the documetation by the use of ``literalinclude``
directives in the description files.  The ``:lines:`` field is used to select
specific parts of the snippet.  The Qt documentation refers to embedded markers
in order to select specific parts and these are retained (but unused) in the
Python version.  Their format is ``# #! [marker]``.

The code snippets can be modified in any way, including renaming the file, so
long as appropriate changes are also made to any description file that includes
them.  A code snippet file may be included by more than one description file.
If a code snippet is modified then the ``:status:`` field of any description
file must not be ``todo`` to prevent the code snippet being overwritten when
re-basing for a new version of Qt.