ubuntu-sdk-bugs team mailing list archive

[Andrea Bernabei <andrea.bernabei@xxxxxxxxxxxxx>]

Public bug reported:

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 :)

** Affects: ubuntu-ui-toolkit (Ubuntu)
     Importance: Undecided
         Status: New

-- 
You received this bug notification because you are a member of Ubuntu
SDK bug tracking, which is subscribed to ubuntu-ui-toolkit in Ubuntu.
https://bugs.launchpad.net/bugs/1603937

Title:
  Documentation: cannot link to Qt QML classes/components

Status in ubuntu-ui-toolkit package in Ubuntu:
  New

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 :)

To manage notifications about this bug go to:
https://bugs.launchpad.net/ubuntu/+source/ubuntu-ui-toolkit/+bug/1603937/+subscriptions