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

Improve the documentation toolchain

    XMLWordPrintable

Details

    • User Story
    • Resolution: Unresolved
    • P1: Critical
    • None
    • None
    • Documentation
    • None
    • 4315cfb44 (dev), 04ebdcb6e (6.4), 4caf38c27 (tqtc/lts-6.2), 0479b02b6 (dev), 4fbcfa43a (6.4), 088acf9ae (dev), 985c281c2 (6.4), 99f1b42b3 (dev), e48afcb0d (6.4), 3c60c8efa (tqtc/lts-6.2), 2160cefd6 (dev), c2c11d067 (dev), 7565650d8 (dev), 225aa4238 (dev)

    Description

      Building the documentation requires the following steps: https://wiki.qt.io/Qt_for_Python/GettingStarted#Building_the_Documentation

      The toolchain works as follows:

      • qdoc is run with .webxml output format
      • shiboken runs over the webxml pages and extracts the parts for which bindings exist (according to its type system) and potentially applies modifications and outputs .rst
      • Referenced C++ code snippets are translated to Python using a regexp-based tool
      • sphinx is run to generate the HTML docs from the .rst files produced and other, fixed pages provided (tutorials etc)

      Attachments

        1. after.mp4
          571 kB
          Cristian Maureira-Fredes
        2. before.mp4
          372 kB
          Cristian Maureira-Fredes

        Issue Links

          relates to

          Epic - Created by Jira Software - do not edit or delete. Issue type for a big user story that needs to be broken down. PYSIDE-1112 Improve Qt for Python documentation

          • P2: Important - Urgent, should be fixed, but will not stop the release.
          • Open

          Bug - A problem which impairs or prevents the functions of the product. QTBUG-86987 qdoc doesn't recognize hidden friends as available APIs

          • P3: Somewhat important - Should be fixed, but doesn't affect the release in any way.
          • Closed

          Bug - A problem which impairs or prevents the functions of the product. PYSIDE-2111 A lot of pages look like an automatic translation of the C++ documentation

          • P4: Low - Would be nice to fix, but it's not very important.
          • Closed
          mentioned in

          Page Loading...

          For Gerrit Dashboard: PYSIDE-1106
          # Subject Branch Project Status CR V
          463264,1 snippets_translate: Fix new string literals tqtc/lts-6.2 pyside/tqtc-pyside-setup Status: ABANDONED 0 0
          463406,3 snippets_translate: Do not append "()" when assigning special values tqtc/lts-6.2 pyside/tqtc-pyside-setup Status: MERGED +2 0
          463943,2 snippets_translate: Fix syntax error 6.4 pyside/pyside-setup Status: MERGED +2 0
          463948,1 snippets_translate: Fix syntax error tqtc/lts-6.2 pyside/tqtc-pyside-setup Status: ABANDONED 0 0
          464921,3 example_gallery: Add .webp image format dev pyside/pyside-setup Status: MERGED +2 0
          465060,2 build_rst_docs: Run example gallery tool dev pyside/pyside-setup Status: MERGED +2 0
          465099,3 build_rst_docs: Inform of requirements-doc.txt requirement dev pyside/pyside-setup Status: MERGED +2 0
          468267,3 Remove generated files from the example project files dev pyside/pyside-setup Status: MERGED +2 0
          468268,3 build_rst_docs: Pass quiet mode to example gallery tool dev pyside/pyside-setup Status: MERGED +2 0
          468549,4 Example gallery tool: Fix repetitive "_" in generated file names dev pyside/pyside-setup Status: MERGED +2 0
          468550,3 Documentation: Add hints about intersphinx troubleshooting dev pyside/pyside-setup Status: MERGED +2 0
          468567,2 build_rst_docs: Pass quiet mode to example gallery tool 6.5 pyside/pyside-setup Status: MERGED +2 0
          468577,2 Remove generated files from the example project files 6.5 pyside/pyside-setup Status: MERGED +2 0
          468634,6 Unify the shiboken sample binding example description dev pyside/pyside-setup Status: MERGED +2 0
          468648,4 Remove generated files from the example project files tqtc/lts-6.2 pyside/tqtc-pyside-setup Status: MERGED +2 0
          468812,4 Example gallery tool: Enable per source file documentation dev pyside/pyside-setup Status: MERGED +2 0
          468816,2 Example gallery tool: Add more file types dev pyside/pyside-setup Status: MERGED +2 0
          469022,2 Example gallery tool: Fix repetitive "_" in generated file names 6.5 pyside/pyside-setup Status: MERGED +2 0
          469024,2 Example gallery tool: Add more file types 6.5 pyside/pyside-setup Status: MERGED +2 0
          469228,2 Example gallery tool: Enable per source file documentation 6.5 pyside/pyside-setup Status: MERGED +2 0
          469229,2 Unify the shiboken sample binding example description 6.5 pyside/pyside-setup Status: MERGED +2 0
          469377,2 Documentation: Add hints about intersphinx troubleshooting 6.5 pyside/pyside-setup Status: MERGED +2 0
          469433,3 snippets_translate: Improve connect handling dev pyside/pyside-setup Status: MERGED +2 0
          469444,2 snippets_translate: Implement rudimentary switch() handling dev pyside/pyside-setup Status: MERGED +2 0
          469501,2 snippets_translate: Improve connect handling 6.5 pyside/pyside-setup Status: MERGED +2 0
          469502,2 snippets_translate: Implement rudimentary switch() handling 6.5 pyside/pyside-setup Status: MERGED +2 0
          469913,2 snippets_translate: Replace :: in switch/case values 6.5 pyside/pyside-setup Status: MERGED +2 0
          469931,2 snippets_translate: Replace :: in switch/case values dev pyside/pyside-setup Status: MERGED +2 0
          470774,2 Fix some doc warnings dev pyside/pyside-setup Status: ABANDONED +1 0
          473680,2 shiboken6: Refactor code snippet extraction 6.5 pyside/pyside-setup Status: MERGED +2 0
          473711,7 shiboken6: Refactor code snippet extraction dev pyside/pyside-setup Status: MERGED +2 0
          473721,3 snippets_translate: Fix repetitive snippet ID lines dev pyside/pyside-setup Status: MERGED +2 0
          474814,7 example_gallery: Fix literalinclude for project files dev pyside/pyside-setup Status: MERGED +2 0
          474866,2 snippets_translate: Fix repetitive snippet ID lines 6.5 pyside/pyside-setup Status: MERGED +2 0
          475011,2 example_gallery: Fix literalinclude for project files 6.5 pyside/pyside-setup Status: MERGED +2 0
          475921,2 example_gallery: Restructure code dev pyside/pyside-setup Status: MERGED +2 0
          475922,3 example_gallery: Ensure tutorials are grouped together dev pyside/pyside-setup Status: MERGED +2 0
          475923,9 example_gallery: Use headline in gallery dev pyside/pyside-setup Status: MERGED +2 0
          475971,2 example_gallery: Restructure code 6.5 pyside/pyside-setup Status: MERGED +2 0
          475978,2 example_gallery: Ensure tutorials are grouped together 6.5 pyside/pyside-setup Status: MERGED +2 0
          477600,3 widgetbinding example: Move .md file around dev pyside/pyside-setup Status: MERGED +2 0
          477601,2 example_gallery: Remove existing target directory dev pyside/pyside-setup Status: MERGED +2 0
          477612,2 example_gallery: Remove existing target directory 6.5 pyside/pyside-setup Status: MERGED +2 0
          477620,2 example_gallery: Use headline in gallery 6.5 pyside/pyside-setup Status: MERGED +2 0
          477622,3 example_gallery: Support markdown dev pyside/pyside-setup Status: MERGED +2 0
          477935,2 example_gallery: Support markdown 6.5 pyside/pyside-setup Status: MERGED +2 0
          485668,2 pointselectionandmarkers example: Fix literalinclude dev pyside/pyside-setup Status: MERGED +2 0
          485677,4 Split out a test driver from the Sphinx inheritance graph generation dev pyside/pyside-setup Status: MERGED +2 0
          485840,2 Split out a test driver from the Sphinx inheritance graph generation 6.5 pyside/pyside-setup Status: MERGED +2 0
          485841,2 pointselectionandmarkers example: Fix literalinclude 6.5 pyside/pyside-setup Status: MERGED +2 0
          488147,2 snippets_translate: Remove _L1, u string/character literals dev pyside/pyside-setup Status: MERGED +2 0
          488355,2 snippets_translate: Remove _L1, u string/character literals 6.5 pyside/pyside-setup Status: MERGED +2 0
          489107,3 snippets_translate: Prevent the variable initialization code from triggering for functions dev pyside/pyside-setup Status: MERGED +2 0
          489576,2 snippets_translate: Prevent the variable initialization code from triggering for functions 6.5 pyside/pyside-setup Status: MERGED +2 0
          523623,3 shiboken6: Make it possible to inject documentation from separate .rst files dev pyside/pyside-setup Status: MERGED +2 0
          523632,3 Move the documentation QUiLoader.registerCustomWidget() out of XML dev pyside/pyside-setup Status: MERGED +2 0
          524026,8 shiboken6/Metabuilder: Prepare for documenting global functions dev pyside/pyside-setup Status: MERGED +2 0
          524027,9 DocGenerator: Refactor doc generation code dev pyside/pyside-setup Status: MERGED +2 0
          524028,11 DocGenerator: Refactor code preparing for generating global functions/enums dev pyside/pyside-setup Status: MERGED +2 0
          524029,11 DocGenerator: Further preparations for generating global functions/enums dev pyside/pyside-setup Status: MERGED +2 0
          524030,12 Document global functions dev pyside/pyside-setup Status: MERGED +2 0
          524452,8 Add a documentation file hint to function/enum type entries dev pyside/pyside-setup Status: MERGED +2 0
          524453,9 Extract global (non-added) function/enum documentation dev pyside/pyside-setup Status: MERGED +2 0
          524633,7 Documentation: Adapt struct ClassDocumentation for header documents dev pyside/pyside-setup Status: MERGED +2 0
          524816,23 Documentation: Use more domain directives from sphinx dev pyside/pyside-setup Status: MERGED +2 0
          525217,2 Documentation: Fix list of additional documents dev pyside/pyside-setup Status: MERGED +2 0
          525337,1 Documentation: Silence some warnings about not finding functions in webxml dev pyside/pyside-setup Status: ABANDONED 0 0
          525362,2 Silence documentation warnings about not finding signals in webxml files dev pyside/pyside-setup Status: MERGED +2 0
          525524,2 Silence documentation warnings about not finding signals in webxml files 6.6 pyside/pyside-setup Status: MERGED +2 0
          525647,2 Documentation: Fix list of additional documents 6.6 pyside/pyside-setup Status: MERGED +2 0
          525772,2 Documentation: Indicate XML parse errors to be warnings in doc_modules.py dev pyside/pyside-setup Status: MERGED +2 0
          525809,2 Documentation: Indicate XML parse errors to be warnings in doc_modules.py 6.6 pyside/pyside-setup Status: MERGED +2 0
          526874,8 Document QtQml's global function as functions dev pyside/pyside-setup Status: MERGED +2 0
          526902,5 Documentation: Enable injecting added function parameter documentation dev pyside/pyside-setup Status: MERGED +2 0
          528054,2 Documentation: Add more string types dev pyside/pyside-setup Status: MERGED +2 0
          528056,3 Documentation: Fix doc modifications for added constructors dev pyside/pyside-setup Status: MERGED +2 0
          528057,3 Documentation: Enable appending to class description dev pyside/pyside-setup Status: MERGED +2 0
          528487,10 doc: spawn many qdoc processes to build the docs dev pyside/pyside-setup Status: MERGED +2 0
          528491,3 Documentation: Add more string types 6.6 pyside/pyside-setup Status: MERGED +2 0
          528493,1 Documentation: Fix doc modifications for added constructors 6.6 pyside/pyside-setup Status: ABANDONED 0 0
          528717,3 shiboken6/Documentation: Add option to disable the inheritance diagram dev pyside/pyside-setup Status: MERGED +2 0
          528718,3 shiboken6/Documentation: Fix sphinx warnings about indexing functions with the identical names dev pyside/pyside-setup Status: MERGED +2 0
          528839,2 shiboken6/Documentation: Add option to disable the inheritance diagram 6.6 pyside/pyside-setup Status: MERGED +2 0
          531892,2 doc: spawn many qdoc processes to build the docs 6.6 pyside/pyside-setup Status: MERGED +2 0
          531975,3 doc: propagate error from qdoc_spawner dev pyside/pyside-setup Status: MERGED +2 0
          532074,2 Documentation: Generate inheritance graph only when base classes exist dev pyside/pyside-setup Status: MERGED +2 0
          532089,2 doc: propagate error from qdoc_spawner 6.6 pyside/pyside-setup Status: MERGED +2 0
          532216,2 Documentation: Generate inheritance graph only when base classes exist 6.6 pyside/pyside-setup Status: MERGED +2 0
          532420,2 doc: Fix error handling in qdoc_spawner dev pyside/pyside-setup Status: ABANDONED 0 0
          532428,7 doc: Fix error handling in qdoc_spawner dev pyside/pyside-setup Status: MERGED +2 0
          532492,2 doc: Fix error handling in qdoc_spawner 6.6 pyside/pyside-setup Status: MERGED +2 0
          532521,7 doc/qdoc_spawner: Restore behavior of bailing out when the core index file exists dev pyside/pyside-setup Status: MERGED +2 0
          544535,2 Documentation: Fix broken links to classes provided as extra documents dev pyside/pyside-setup Status: MERGED +2 0
          544536,2 Documentation: Add support for decorators dev pyside/pyside-setup Status: MERGED +2 0
          544537,2 Documentation: Change slot page to be a proper decorator dev pyside/pyside-setup Status: MERGED +2 0
          544538,2 Documentation: List loadUiType() as a function instead a class dev pyside/pyside-setup Status: MERGED +2 0
          544608,3 Documentation: Change Enum page to be a proper decorator dev pyside/pyside-setup Status: MERGED +2 0
          545677,2 doc/qdoc_spawner: Restore behavior of bailing out when the core index file exists 6.6 pyside/pyside-setup Status: MERGED +2 0
          556593,3 Documentation: Fix ClassInfo to be a proper decorator dev pyside/pyside-setup Status: MERGED +2 0
          556628,2 Documentation: Fix ClassInfo to be a proper decorator 6.7 pyside/pyside-setup Status: MERGED +2 0

          Activity

            People

              kleint Friedemann Kleint
              ablasche Alex Blasche
              Alex Blasche Alex Blasche
              Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

                Created:
                Updated:

                Gerrit Reviews

                  There are no open Gerrit changes