desktop-dx-o-unity-api-docs

Registered by David Barth

Improve the API documentation for Unity

Blueprint information

Status:
Not started
Approver:
None
Priority:
Undefined
Drafter:
None
Direction:
Needs approval
Assignee:
Canonical Desktop Experience Team
Definition:
New
Series goal:
None
Implementation:
Unknown
Milestone target:
None

Related branches

Sprints

Whiteboard

Work items:
[njpatel] request upstream valac developers to change valac in a way it leaves the comments in, thus generating documentation from comments in code is easier:
[njpatel] Talk to to gir-scanner upstream to export gtk-doc method annotations:
[njpatel] Find out which format devhelp uses in order for giraffe to provide additional devhelp output:

Session notes:
This is a follow-up to https://launchpad.net/ubuntu/+spec/appdevs-dx-n-unity-places-api

Documentation available at http://developer.ubuntu.This is a follow-up to https://launchpad.net/ubuntu/+spec/appdevs-dx-n-unity-places-api

Overview: https://wiki.ubuntu.com/DeveloperUbuntuComApi
Documentation available at http://developer.ubuntu.com/api/

Other URL shortcuts:
http://developer.ubuntu.com/api/ubuntu-11.04
http://developer.ubuntu.com/api/devel/
http://developer.ubuntu.com/api/devel/GIR/ (C and Python bindings for libraries supporting GObject introspection)

For GObject-based libraries we achieve multiple binding output by processing GIR files with a tool called giraffe: https://launchpad.net/giraffe

How is the current online documentation generated:
- HTML docs extracted from -doc binary packages
- For libraries supporting GObject introspection, we process .gir files from -dev packages and create C and Python docs
- This documentation is then published weekly at http://developer.ubuntu.com/api/

URL scheme: language/api (developers are generally interested in one particular language)
https://bugs.launchpad.net/giraffe
* Wicked (that's the name of a tool)

TODO:
* Is there a better approach?
* Better theme integration with d.u.c
* The current method needs some improvements
  - Linking between docs
  - ...com/api/

Requested documentation: what about nux?
 nux is still moving too much to justify it being documented for the "outside" right now

(?)

Work Items

This blueprint contains Public information 
Everyone can see this information.