Defining a stable API and docs for desktop development
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:/
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
- Started by
- Completed by
Whiteboard
Summary
Ubuntu has a very good starting poin for developers: developer.
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.
* From the page, you can access some APIs, but they are not visually integrated with the rest of developer.
* 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://
* static versions of documentation available for download as a single file
* devhelp (see also https:/
[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/
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
* 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_
* 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:/
- 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.
- 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://
- Tutorials (we need help!):
-- http://
-- http://
-- https:/
