Cannot generate API web docs from source

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.

I've added a proper initial Ubuntu theme to the branch [1] and rebuilt the output:
http://people.canonical.com/~knitzsche/yuidoc-ubuntu-html5-theme/17oct2013/index.html

[1] https://code.launchpad.net/~knitzsche/ubuntu-html5-theme/ubuntu-html5-theme-yuidoc

Added docs for lists.js
http://people.canonical.com/~knitzsche/yuidoc-ubuntu-html5-theme/17oct2013/index.html

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.

Hi Daniel,

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

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

@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.

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

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

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

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

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.

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

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.

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)

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