Ubuntu Wiki

• Launchpad entry: TBD

• Created: 2012-06-28

• Contributors: mhall119 jonobacon

Create a new web project for hosting searchable, browseable and editable documentation for the APIs that are used in Ubuntu application development.

Rationale

Our API documentation is sparse and in static HTML. This makes it difficult to find specific documentation.

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)

Backend

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.

GDN

GDN provides models that mirror the data structures on the GObject libraries, and will populate them with GObject Introspection data for those libraries.

View full size

Language Models

In order to present the same APIs in multiple languages, we will need to wrap the GDN API models with something that will be able to convert them into programming-language specific names and formats.

ProgrammingLang

Will represent one of the available programming languages in the system

• id - Auto-generated primary key

• language_name - Name of the programming language

• translator - Name of a Python class used for translating GDN APIs into this language

LanguageNamespace

Links a GDN Namespace record to a programming language, as some APIs may only be usable to a subset of languages

• id - Auto-generated primary key

• language - Foreign key to a ProgrammingLang record

• namespace - Foreign key to a GDN Namespace record

Translator

This will by a python class, but not a Django model. We will need a Translator class for each language we want to support. A Translator class will be responsible for converting GDN API data models into documentation specific to it's given programming language. Initially, we will have the following Translators:

• Python

• C

• C++

Platform Models

These models will be used to define the platform that application developers can target. A platform is the combination of libraries and APIs provided by a given release of a distribution.

Distro

This model will represent a reusable reference to a distro (Ubuntu, Kubuntu, Xubuntu, etc)

• id - Auto-generated primary key

• name - Name of the distribution

• website - URL to the distro's homepage

• description - Long text description of the distro

DistroRelease

This model will represent a specific release of a distribution, and will be used to define what libraries and versions of them are available in that release.

• id - Auto-generated primary key

• version - Official release version name or number

• codename - Development codename for the release

• release_date - Date when this was released

• expiration_date - Date that support for the release ends

PlatformSection

This model will be used to group PlatformItems by areas of focus, such as Graphical Interface, Filesystem, Multimedia, etc.

• id - Auto-generated primary key

• section_name - Name of the section

• section_description - Short text (on sentence) describing the contents of the section

PlatformItem

This model is used to define a platform, it links GDN libraries of a specific version to a specific DistroRelease

• id - Auto-generated primary key

• distro_release - Foreign key to a DistroRelease record

• library_release - Foreign key to a GDN Namespace record

• section - Foreign ey to a PlatformSection record

• packages - Comma-separated list of distro packages that provide this library

Support Models

The frontend will have a number of Django models specific to Ubuntu, making use for the GDN data models.

ReleatedQuestion

Will link a question on AskUbuntu.com to a GDN api element

• id - Auto-generated primary key

• node - Foreign key to a GDN Node record

• question_text - Short text of the question (one sentence)

• question_url - URL to a website (AskUbuntu or other) where the rest of the question and it's answer can be found

RelatedTutorial

Will link an online tutorial (likely on developer.ubuntu.com, but not exclusively) to a GDN api element

• id - Auto-generated primary key

• node - Foreign key to a GDN Node record

• tutorial_name - Short name of the tutorial

• tutorial_url - URL to the website with the tutorial

RelatedSnippets

Will contain short pieces of code demonstrating the use of a GDN api element

• id - Auto-generated primary key

• node - Foreign key to a GDN Node record

• snippet_name - Short name of the code snippet

• snippet_code - Long text field containing the full code snippet

RelatedImage

An uploaded image showing the visible result of a GDN api element

• id - Auto-generated primary key

• node - Foreign key to a GDN Node record

• image_name - Short name or title of the image

• image_caption - Short caption (one sentence) describing the image

• image_url - URL to the image

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.

URLs

Paths will have two parts, the first will contain the Distro, then DistroRelease and ProgrammingLang. After that will come the Namespace, node type (class, enum, etc) and finally the name of the Node:

• /api/ubuntu/12.04/python /Unity/class/LauncherEntry/
• /api/ubuntu/12.04/c /Unity/class/LauncherEntry/

Views should contain anchor links to all API elements on the page:

• /api/ubuntu/12.04/python/Unity/class/LauncherEntry/#get_for_desktop_file

Site Index

The main page of the site should provide a brief (on paragraph) text explaining the purpose of the site, followed by a list of Distro records available, each one linking to it's Distro Page.

Distro Page

The Distro page will display the name of the distro, a link to it's homepage, and it's description. Below that, it will provide a list of DistroRelease records. This list will contain only supported releases (those that have not reached their expiration_date) ordered by release_date.

Release Page

The Distro Release page will list all of the PlatformItem records for the DistroRelease, grouped by PlatformSection. Each item will be presented by the GDN Namespace name, followed by links for each of the languages supported by that Namespace as defined by the LanguageNamespace data models.

Namespace Page

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

Class Page

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.

Function Page

Search Results Page

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.

Management Commands

TBD

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.

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.

Qt API support

• Needs to support "protected" methods in addition to "public" and "private" ones.
• Add "is_destructor" field on Function
• Add "Q_INVOKABLE" field on Function to indicate whether it is accessible by QML
• Add "constant" boolean field to Property
• Look into using gtype_name to store Qt type strings

Extra description

• Needs long-text description field on Node (or a model that wraps Node)

Copy-forward

• When a new version of a library comes out, all support data should be forward-copied to it

• When a new release of a distro is defined, the previous PlatformItems should be forward-copied to it

CategorySpec