Cannot generate API web docs from source

Bug #1241029 reported by Kyle Nitzsche on 2013-10-17
16
This bug affects 3 people
Affects Status Importance Assigned to Milestone
Ubuntu HTML5 UI SDK
Medium
Kyle Nitzsche
ubuntu-html5-theme (Ubuntu)
Undecided
Unassigned

Bug Description

Today, we cannot generate JavaScript API web docs for from the source JavaScript.

(A community member (Daniel Beck thanks!) has put together an excellent set of pages [1] instructing how to use the Ubuntu HTML5 widgets including overall explanation, the JavaScript API, and some content on CSS. But these appear hand-crafted and not generated from source. )

It seems important to be able to generate API docs from source automatically for at least these reasons:
 * Automation and maintenance: When a new version is released, there should be a clear path to generating the API docs and publishing them, with no handcrafting required
 * Engineering responsibility: placing the API doc content in the source itself clearly makes engineers who change the API responsible for keeping the API docs synchronized

To this end, I implemented a first pass at adding comments to source such that API docs can be generated. I used yuidoc format.
 * Here's what is generated today: http://people.canonical.com/~knitzsche/yuidoc-ubuntu-html5-theme/17oct2013/
 * Here's the branch that includes the yuidoc from which that was produced: https://code.launchpad.net/~knitzsche/ubuntu-html5-theme/ubuntu-html5-theme-yuidoc

Some parts are not yet done (lists.js (now done), toolbars.js, popovers. fastbuttons.js)

Many are "done" to first pass level: core.js, pagestack.js, tabs.js, dialogs.js, buttons.js.

The generated web pages are (obviously) not Ubuntu themed, which can be changed.

Is there a good reason to use a different system (jsdoc for instance)?

[1] http://daniel-beck.org/ubuntu-html5-theme/widgets/

Revision history for this message
Daniel Beck (d-danielbeck) wrote :

This would be great. I only created the reference documentation on my homepage because the developer documentation was needed for Ubuntu 13.10. Javadoc like documentation is *definitely* the better way to create an API documentation.

YUI doc is in my opinion a very good tool.

If there is interest for it, I could create a branch and import the documention on my homepage in the sourcecode. However, if someone else want to do that, feel free to so.

Revision history for this message
Kyle Nitzsche (knitzsche) wrote :
Revision history for this message
Kyle Nitzsche (knitzsche) wrote :
description: updated
Revision history for this message
David Barth (dbarth) wrote :

Kyle: You should turn the branch into a merge proposal to get more feedback. The docs look really nice to me, both the content/structure and the stylesheet as well.

Revision history for this message
David Barth (dbarth) wrote :

Hi Daniel,

It would be great indeed if you can manage to integrate the content of your documentation into the code.

Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

Hi Daniel and David,

I am going to complete the first pass of the API documentation hopefully today or very soon in my branch then MP it.

Then after the merge, I think Daniel can propose material from his content if he wants.

This way I we start with a fully consistent approach (there are a lot of ways to use the yuidoc tags.). It is less work I think this way.

I am going through the JavaScript code very methodically and implementing/testing every method in an Ubuntu SDK app: lp:~knitzsche/+junk/html5api. This allows me to deduce HTML5 declaration options and find and report bugs such as
* list.remove() fails (code typo): https://bugs.launchpad.net/ubuntu-html5-theme/+bug/1241215

(This html5api demo app goes farther in exercising the API than the default projects created in the SDK and the sample rss-reader app - I wonder if it would be helpful to make it a standard part of the kit.)

Revision history for this message
Adnane Belmadiaf (daker) wrote :

@Kyle the list.remove() typo has a MR if you want to approve it, also i'll fix the tabs coding style and be more strict in code reviewing next time.

Adnane Belmadiaf (daker) on 2013-10-19
Changed in ubuntu-html5-theme:
status: New → Triaged
assignee: nobody → Kyle Nitzsche (knitzsche)
importance: Undecided → Medium
Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

I have made a merge proposal for this bug that's also for a another (related) bug: https://code.launchpad.net/~knitzsche/ubuntu-html5-theme/ubuntu-html5-theme-yuidoc/+merge/192213

Changed in ubuntu-html5-theme:
status: Triaged → In Progress
Adnane Belmadiaf (daker) on 2013-11-19
Changed in ubuntu-html5-theme:
status: In Progress → Fix Committed
Revision history for this message
Launchpad Janitor (janitor) wrote :

This bug was fixed in the package ubuntu-html5-theme - 0.1+14.04.20140107-0ubuntu1

---------------
ubuntu-html5-theme (0.1+14.04.20140107-0ubuntu1) trusty; urgency=low

  [ Adnane Belmadiaf ]
  * s/parentNode/parendNode Spaces instead of tabs. (LP: #1241215)
  * Add option selector widget. (LP: #1232533)

  [ daker ]
  * Passe the UI variable name so we will not lock the variable. (LP:
    #1222878)
  * Made variable declaration locale. (LP: #1222881)
  * Fixed z-index for the list items aside. (LP: #1223973)
  * s/parentNode/parendNode Spaces instead of tabs. (LP: #1241215)
  * Space instead of tab. (LP: #1240682)
  * Made list items with headers differentes. (LP: #1246446)
  * Updated the progressbar component to match the design.
  * Move tabs closer to what they should be, Expand API to match the QML
    one (at least at the Tabs level), .
  * Add option selector widget. (LP: #1232533)

  [ Kyle Nitzsche ]
  * Add button id to "Invalid button ID" error message .
  * This MR does three main things: 1) Implements yuidoc comments in all
    js files to support API doc generation, and provides yuidoc assets
    (theme dir and json file) needed to build the API docs. Bug LP:
    #1241029 3) Provides JS classes for shape and page with
    corresponding UbuntuUI prototype constructor functions. Bug LP:
    #1243248 4) Adds a getEl(UbuntuUIObject) to return the element for
    any Ubuntu class. Also LP: #1243248. (LP: #1243248, #1241029)

  [ Colin Watson ]
  * Make ubuntu-html5-theme Multi-Arch: foreign.

  [ Alexandre Abreu ]
  * Fix exec path in app-gallery app desktop file. (LP: #1235321)
  * Add convenient element() function to most widgets ... (we might want
    to factor those out in a second step).
  * Move tabs closer to what they should be, Expand API to match the QML
    one (at least at the Tabs level), .
  * Add HTML5 webapp container package.

  [ Ubuntu daily release ]
  * Automatic snapshot from revision 98
 -- Ubuntu daily release <email address hidden> Tue, 07 Jan 2014 23:46:53 +0000

Changed in ubuntu-html5-theme (Ubuntu):
status: New → Fix Released
Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

Here is the method I use to generate the docs from ubuntu-html-theme source:

# install npm
sudo apt-get install npm

# use npm to install yuidocjs globally
sudo npm -g install yuidocjs

# get ubuntu-html5-theme source branch
bzr branch lp:ubuntu-html5-theme

# move to the js dir
cd ubuntu-html5-theme/0.1/ambiance/js

# generate the docs from source
yuidoc -c yuidoc.json .

# docs are in new ./build/ dir

Revision history for this message
Michael Hall (mhall119) wrote :

Trying the steps above on 13.10 I run into the following error:

mhall@mhall-thinkpad:~/projects/Ubuntu/sdk/ubuntu-html5-theme/0.1/ambiance/js$ yuidoc -c yuidoc.json .
/usr/bin/env: node: No such file or directory

tags: added: html5-blocker
Revision history for this message
David Barth (dbarth) wrote :

You need to use the nodejs package that comes from our Cordova PPA. It contains the right link from node to nodejs.

https://launchpad.net/~cordova-ubuntu/+archive/ppa

Otherwise, Robert needs to land that in trusty proper to get rid of those node/nodejs issues.

Revision history for this message
David Barth (dbarth) wrote :

Kyle or Robert, can you make this package depend on nodejs-legacy, and you will get the right alias for node.

Revision history for this message
Robert Bruce Park (robru) wrote :

If your package depends on /usr/bin/node being a symlink to /usr/bin/nodejs, then you need to install the nodejs-legacy package, which is already in the archive (don't be scared by the name 'legacy', that's just what debian people call it because they are trying to rename THE ENTIRE WORLD from node to nodejs). It's legit and it's not going anywhere.

Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

Bruce, yes. The issues is that yuidoc's wrapper starts with this shebang: #!/usr/bin/env node

However: 'node' is not an executable on PATH.

Installing nodejs-legacy adds a symlink: lrwxrwxrwx 1 root root 6 Dec 23 00:17 /usr/bin/node -> nodejs

After which the above procedure should work (I think added a similar symlink manually way back when and forgot about it - my bad)

Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

Here is the *REVISED* method I use to generate the docs from ubuntu-html-theme source:

# install npm
sudo apt-get install npm nodejs-legacy

# use npm to install yuidocjs globally
sudo npm -g install yuidocjs

# get ubuntu-html5-theme source branch
bzr branch lp:ubuntu-html5-theme

# move to the js dir
cd ubuntu-html5-theme/0.1/ambiance/js

# generate the docs from source
yuidoc -c yuidoc.json .

# docs are in new ./build/ dir

David Barth (dbarth) on 2014-01-28
Changed in ubuntu-html5-theme:
status: Fix Committed → Fix Released
David Barth (dbarth) on 2014-01-31
Changed in ubuntu-html5-theme (Ubuntu):
status: Fix Released → Fix Committed
Changed in ubuntu-html5-theme:
status: Fix Released → In Progress
Changed in ubuntu-html5-theme (Ubuntu):
status: Fix Committed → In Progress
Changed in ubuntu-html5-theme:
status: In Progress → Fix Committed
Changed in ubuntu-html5-theme:
status: Fix Committed → Fix Released
Changed in ubuntu-html5-theme (Ubuntu):
status: In Progress → Fix Released
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers