Defining a stable API and docs for desktop development

Registered by Andrea Grandi on 2011-10-29

We should start creating Ubuntu API specification and documentation. At the moment if someone wants to write an application for Ubuntu, he has to search the web to know how to do common things. For example: how do I empty the Trash? How do I add my application to the notify area? How do I create a Control Panel window setting?

More information on the wiki: https://wiki.ubuntu.com/UbuntuDevelopmentAPI

Blueprint information

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

Related branches

Sprints

Whiteboard

Summary

Ubuntu has a very good starting poin for developers: developer.ubuntu.com
but we surely need lot of things to attract more developers and make Ubuntu development easier.

What we need

- Documentation - improved documentation: nothing original here in my mind. My idea is simply to have something very similar to Qt documentation. Finding a library must be easy and fast. All libraries must be documented. Actual documentation is not complete. Take a look, for example, at this one http://developer.ubuntu.com/api/ubuntu-11.10/cplusplus/dbusmenu-qt/index.html

developer.ubuntu.com
 * From the page, you can access some APIs, but they are not visually integrated with the rest of developer.ubuntu.com
   * Therefore, have the same CSS
   * ted points out that some of the docs are generated, and that we should try to make the output of the various generation tools look the same
     * A standardized intermediate format would make this simpler
     * Also, should be a default doc generation tool for Ubuntu platform APis
       * When using GTK+, you'll need to use their tools
       * Use doxygen otherwise
    * devhelp documentation integration in Qt Creator IDE: http://taschenorakel.de/mathias/2011/11/01/devhelp-books-qtcreator/
 * static versions of documentation available for download as a single file
   * devhelp (see also https://bugs.launchpad.net/ubuntu/+source/devhelp/+bug/882805)

[jml] explore getting developer.u.c into devhelp: TODO
[jml] look at documentation already on developer.u.c, figure out how it was generated, see what would make a good intermediate format: TODO
[jml] once format decided, publish standard recipes for getting docs into that format: TODO
[jml] something to translate from intermediate format into sexy thing for developer.u.c: TODO

Open question:
 * gobject generates C documentation, but Python devs hate that. How can we get language-specific documentation for gobject? giraffe is the answer, but is not complete.

[ted] Publish new coding standards for DX such that all API docs have code examples: TODO
[ted] Move API docs out of wiki into the source packages and thus to d.u.c: TODO
[andreagrandi] Look at source code for Ubuntu platform APIs, generate a list of undocumented public methods/classes/functions and automatically file bugs for these: TODO

Rick says it should be required to have code examples in API docs. DX has a make rule such that you cannot add public APIs without documentation. Was a tough transition.

What _are_ the "Ubuntu platform APIs"?
Native Development:
  * GNOME 3 (probably needs to be broken up a bit)
  * gobject
  * libunity
  * libappindicator
  * gsettings
  * UbuntuOne (REST APIs?)

[ted] Document standard practices in DX development for API usage: TODO

- Stable API - we must define a stable API for desktop libraries and keep it stable. In this case I only have few examples that come in my mind but I hope it will clarify the problem. When I needed to read a setting I didn't know if it was better to use gsettings, dconf etc.... Changing the implementation from a release to another can be ok, but we need to keep the same API call: getSettingValue(...) method (it's just an example) must remain the same for years, however you decide to implement the underline API. Don't think only to amateur developers, think also to professional companies. If you've investigated a little, you'll know that one of the reasons why they don't develop for Linux is why the libraries and API often changes from a distribution to another and from a release of a distribution to another.

 * bare minimum: announce highly unstable APIs (force to use a C #define before the #include if the API will change in the future. e.g. libgdu uses #define GDU_API_IS_SUBJECT_TO_CHANGE so the developers know that APIs are subject to change)
 * ideal: don't break backwards compatibility without a long, known deprecation period

Unity project documentation
 * Would be good to have more documentation on how to hack on unity itself (other notes are about improving documentation for using unity as a developer) Look here (https://bugs.launchpad.net/ayatana-design/+bug/727901) : there is an example on how unity developers can help fixing bitesize bugs and backlog ones.

- Code examples - it's very difficult to find code examples of Ubuntu libraries, in particular Unity libraries. Many times I had to modify something, I needed to ask to some Unity developer or trying to find the code by myself. This doesn't really speed up the Ubuntu development. There should be clear and easy tounderstand examples of every library used. How do I use the notify bar? How do I interact with Unity Launcher? How do I access the Unity libraries. Once again, developer.ubuntu.com has some hints and examples, but the documentation should be more complete.

- Bindings - We must be sure, when we release a library or a new API that at least we cover the main languages available. C (Vala), C++/Qt, Python should have API bindings available.

- Code documentation - We must improve code documentation so that the generated docs is better
(see above)

What about sysadmin docs? It's very difficult to find information about enterprise deployment (e.g. disabling suspend/hibernation on per group basis, LDAP integration). Current PolicyKit documentation is either outdated or nonexistant.

References

- Existing documentation: http://developer.ubuntu.com/api/
- Tutorials (we need help!):
-- http://developer.ubuntu.com/community/submit-a-tutorial/
-- http://developer.ubuntu.com/resources/tutorials/all/
-- https://blueprints.launchpad.net/ubuntu/+spec/community-p-app-developer-tutorial-growth

(?)

Work Items