Details

    • Type: User Story
    • Status: In Progress
    • Priority: P4: Low
    • Resolution: Unresolved
    • Affects Version/s: dev
    • Fix Version/s: 5.11.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      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?

        Attachments

          Issue Links

          For Gerrit Dashboard: PYSIDE-363
          # Subject Branch Project Status CR V

            Activity

              People

              • Assignee:
                kleint Friedemann Kleint
                Reporter:
                kleint Friedemann Kleint
                RnD Owner:
                Alex Blasche
              • Votes:
                1 Vote for this issue
                Watchers:
                4 Start watching this issue

                Dates

                • Created:
                  Updated:

                  Time Tracking

                  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

                    Gerrit Reviews

                    There are no open Gerrit changes