Documentation: cannot link to Qt QML classes/components

Bug #1603937 reported by Andrea Bernabei
10
This bug affects 2 people
Affects Status Importance Assigned to Milestone
ubuntu-ui-toolkit (Ubuntu)
High
Christian Dywan

Bug Description

staging branch, revision 2033

Description
Linking to Qt QML classes/methods/components when writing documentation for UITK components does not work.
If you want to link to, say, the Text component while writing the documentation for a UITK component, you should be allowed to use "\l Text", and it should just work.
At the moment, it doesn't, qdoc fails with "Can't link to Text".

Looking at the current documentation, it seems the documentation writers mainly used 2 workarounds:
1) Do not link to Qt classes/components/properties at all. This is clearly suboptimal, but it seems 95% of the writers went this way.
2) Hardcode the absolute URL to the Qt docs. This of course means that those links will break when the webpage at that URL will change address.
Example: links at https://developer.ubuntu.com/api/qml/sdk-15.04.5/UbuntuUserInterfaceToolkit.ubuntu-layouts/ are broken, because they point to https://qt-project.org/doc/qt-5.0

See http://bazaar.launchpad.net/~ubuntu-sdk-team/ubuntu-ui-toolkit/staging/view/2033/documentation/ubuntu-layouts.qdoc#L29

The docs.sh script specifies that the cross-referencing of docs is only done for the ONLINE documentation, although I don't see why that is the case.
http://bazaar.launchpad.net/~ubuntu-sdk-team/ubuntu-ui-toolkit/staging/view/2033/documentation/docs.sh#L39

Is there any reason?

If not, we should add "indexes" to the offline documentation, so that we can start fixing the documentation files by removing hardcoded URLs and adding links to Qt docs in as many places as possible :)

Related branches

Revision history for this message
Launchpad Janitor (janitor) wrote :

Status changed to 'Confirmed' because the bug affects multiple users.

Changed in ubuntu-ui-toolkit (Ubuntu):
status: New → Confirmed
Changed in ubuntu-ui-toolkit (Ubuntu):
assignee: nobody → Christian Dywan (kalikiana)
importance: Undecided → High
status: Confirmed → In Progress
Changed in ubuntu-ui-toolkit (Ubuntu):
status: In Progress → Fix Committed
Revision history for this message
Launchpad Janitor (janitor) wrote :

This bug was fixed in the package ubuntu-ui-toolkit - 1.3.2060+16.10.20160814

---------------
ubuntu-ui-toolkit (1.3.2060+16.10.20160814) yakkety; urgency=medium

  [ Zoltan Balogh ]
  * Fix OptionSelectorTestCase tests.
  * Fix more OptionSelector autopilot tests

  [ Timo Jyrinki ]
  * Disable documentation building for GLES builds. Fixes LP: #1606222.
  * Replace abs with qFabs due to GCC6 breakage. Fixes LP: #1610943.
  * Limit s390x dependencies more due to upstart/s390x problems and removed
    packages in archives. Fixes LP: #1610951

  [ Andrea Bernabei ]
  * ListItemLayout doc: add elide mode change example and add section about
    labels default properties values. Fixes LP: #1603450.
  * ListItemLayout doc: add explicit note about the need to bind ListItem's
    height to layout's height.
  * More Scrollbar optimizations: 20% faster creation time. Fixes LP: #1606451
  * Scrollbar: fix wrong thumb color on tap/mouse release and increase coverage
    of hover states unit tests. Fixes LP: #1608897

  [ Zsombor Egri ]
  * Fix null pointer property initializer used with 1.3 PageWrapper.
    Fixes LP: #1604780.
  * Fix BottomEdge content URL preloading. Fixes LP: #1604509.

  [Albert Astals Cid ]
  * UCUnits::resolveResource: Prefer image path if it exists. This saves
    searching the disk for @gu images, which is a big speedup. According to
    callgrind loading 100 images from a folder that contains 380 images goes
    from around 3 million instructions per UCUnits::resolveResource call down
    to around 10 thousand. This optimization is ok since it is not correct to
    ship both image.png and image@20.png. You either have to ship gu-enabled
    files or not, but mixing them is not allowed. Searched for cases in which
    that may be happening in my phone and found none. Fixes LP: #1604029.

  [ Tim Peeters ]
  * Configure colors of the buttons in the ActionBar and PageHeader through
    their Styles. Fixes LP: #1597774.
  * Fix assigning of constant values to a grouped property in StyleHints.
    Fixes LP: #1602836.
  * Fix list view keyboard navigation for RightToLeft and BottomToTop
    directions. Fixes LP: #1605634
  * Use external QML files instead of embedded QML strings for autopilot tests.
    Fixes LP: #1578319
  * Fix failing autopilot header tests.
  * Fix ActionSelectionPopover Autopilot CPO tests.

  [Christian Dywan ]
  * Include indexes in "offline" docs and filter out link errors.
    Fixes LP: #1603937.
  * Increase focus ring thickness from 1dp to 2dp. Fixes LP: #1602690.
  * Add a snippet about tests to the toplevel README
  * Enter/Return to trigger, Space to expand ComboButton. Fixes LP: #1523817.
  * Initialize engine variable before using it in the _engine case.
  * Use Qt.rgba instead of #0000 checking ListItem default color.
    Fixes LP: #1560004
  * Don't use a different .desktop file in the gallery tests.
    Fixes LP: #1578319
  * Update scaling docs, set QT_SCALE_FACTOR and unset GRID_UNIT_PX.
    Fixes LP: #1610208

  [ Florian Boucault ]
  * Sections: load Icons asynchronously.

 -- Zoltán Balogh <email address hidden> Sun, 14 Aug 2016 09:06:46 +0000

Changed in ubuntu-ui-toolkit (Ubuntu):
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers