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

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

            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