Prerequisites

• Shiboken build with docs (requires libXSLT, libXML2)
• Module sphinx sphinx_rtd_themes
• Pass path to Qt source via setup.py -qt-src-dir (unless in-source build or installed SDK)
• Presence of dot (graphviz)
• qdoc with WebXML output format (Qt 5.11 or higher)

Process

• qdoc generates documentation in WebXML
• shiboken code generator transforms them to .rst files applying some modifications specified in the PySide2 .xml files.
• The sphinx tool is used to create documentation using various conf.py files. For example from the build

How to test

• In the build dir (fex pyside-setup-dev/testenv_dev_22_build/py2.7-qt5.11.0-64bit-release/pyside2), run make apidoc
• launch doc/html/index.html
• To re-run sphinx only in the doc folder:

  sphinx-build -b html rst html
  

  Relevant commits

• "Pass the include paths to qdoc", e5312f9ca5d38230e397d05190e623b083724bf5 qtbase/ https://codereview.qt-project.org/#/c/153214/
• "Move the documentation for the classes to their modules." e86df8cc4b6a522fac909687d48b269c7f5108b6 https://codereview.qt-project.org/#/c/5520/

Open Issues

• .qddoconf files for multiple modules (as for Qt3D) are not handled correctly
• qdoc produces less output when run against a shadow build/installed package compared to an in-source developer build (still missing include paths)?
• Find a featured example?
• Snippets (see below)

Snippets

Snippets are resolved by shiboken2 in the doc transformation process (approx 490).

• quotefile does not work for module != qtbase (qtxmlpatterns/quiloader). Need to split "library-source-dir" to accept a path as well
• Snippets for new code not found
• Some snippets no longer found or reorganized/completely rewritten in Qt 5.

ToDo

• After running qdoc over each module, shiboken runs on a generated header containing all modules. Works currently but may not scale in the future. Split this somehow?