DeveloperNetwork
Create a new web project for hosting searchable, browseable and editable documentation for the APIs that are used in Ubuntu application development.
Contents
Rationale
Our API documentation is sparse and in static HTML. This makes it difficult to find specific documentation.
User stories
- Alice is writing an new app in Python and GTK3, she wants to lookup specific GTK3 classes as well as their methods, properties and signals.
- Bob is adding an Application Indicator to his program, and needs to see the correct API to use as well as example of it's use.
Required Functionality
- Parse GObject introspection data and save it in discrete fields in a database
- Display API in multiple programming languages (C, Python, Vala, etc)
- Allow searching all the API fields
- Allow multiple versions of the same API (Gtk 3.4, Gtk 3.5, etc)
- Define collections of API versions as a distro release (Ubuntu 12.04, Ubuntu 12.10, etc)
- Allow linking between one API and another
- Allow manual addition of descriptions, explanations and examples (using markup)
User Experience
The goal of the site is to pull together quality machine generated documentation with the ability for users to contribute content. The goal here is to also bring together other useful support and resources into the site.
The user experience would work like this. Firstly the user can browse different libraries that are available in this system (this would initially be GObject Introspection libraries):
You can see on the right that there are a series of questions linked from Ask Ubuntu and a clear place to ask further questions.
When a user clicks a library they see the following as an example:
Here we break the library down into sections so the user can more easily browse them. We also provide a list of tutorials of general interest to GTK+ (these could be from the cookbook portion of the site. We may also want to include some general user-added documentation here (e.g. such as an introduction to GTK).
When a user clicks on a class we see the class information page:
This page has a number of features:
- The function / signal / properties are shown at the top for those developers who want a quick reference.
- This reference content is displayed for the appropriately selected language (the language selector is at the top of all pages).
- The description box can be user submitted and edited content providing a good introduction to the class.
- The right sidebar includes user editable content such as a single line summary of the class, a screenshot for visible widgets and user submitted samples of the class in action.
- We would enable Disqus commenting on each page too.
Editing Content
To edit content users will need to be in a particular launchpad group (for example the docs team could be part of the group) and users who have permission will see small edit button next to each field (similar to Launchpad). There inline editing can occur:
The site would support markdown format to make it easy for users to edit and submit content.
Code Layout
We will be building this on top of the initial work done by Alberto Ruiz on Gnome Developer Network (GDN), building an interactive web frontend to display the API data already available in the database backend.
Data Models
GDN provides models that mirror the data structures on the GObject libraries, and will populate them with GObject Introspection data for those libraries.
Web Frontend
The web frontend should be built in a separate Django application from GDN's 'api' application, so that GDN itself can remain generic enough to be used by other distros and projects. Any non-Ubuntu specific additions should be made here and submitted upstream.
Theme
This project should use the community Django theme as much as possible, with site-specific css and javascript being added to the above web frontend code.
Implementation
Models
The frontend will have a number of Django models specific to Ubuntu, making use for the GDN data models:
DistroRelease - Will group multiple GDN library versions to a specific release of Ubuntu
RelatedQuestion - Will link a question on AskUbuntu.com to a GDN api element
RelatedTutorial - Will kink an online tutorial (likely on developer.ubuntu.com, but not exclusively) to a GDN api element
RelatedSnippets - Will contain short pieces of code demonstrating the use of a GDN api element
RelatedImage - An uploaded image showing the visible result of a GDN api element
Views
TBD
Management Commands
TBD
Unresolved issues
Highlight any issues that should be addressed in further specifications, and not problems with the specification itself; since any specification with problems cannot be approved.