Uploaded image for project: 'Qt for Python'
  1. Qt for Python
  2. PYSIDE-363

Fix documentation generation

XMLWordPrintable

    • Icon: User Story User Story
    • Resolution: Done
    • Icon: P4: Low P4: Low
    • 5.11.0
    • None
    • Documentation
    • None

      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?

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

            kleint Friedemann Kleint
            kleint Friedemann Kleint
            Alex Blasche Alex Blasche
            Votes:
            1 Vote for this issue
            Watchers:
            5 Start watching this issue

              Created:
              Updated:
              Resolved:

                Estimated:
                Original Estimate - 2 weeks, 2 days
                2w 2d
                Remaining:
                Remaining Estimate - 2 weeks, 2 days
                2w 2d
                Logged:
                Time Spent - Not Specified
                Not Specified

                  There are no open Gerrit changes