DeveloperNetwork
|
Size: 15721
Comment:
|
Size: 16029
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 19: | Line 19: |
| * Allow searching all the API fields | * Allow searching the API fields |
| Line 25: | Line 25: |
| == Backend == We will be building this on top of the initial work done by Alberto Ruiz on [[https://github.com/aruiz/GDN/|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. {{attachment:api_models_small.png}} [[attachment:api_models.svg|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 === |
=== Data Model === The API data will be parsed from many different sources, pre-rendered into HTML, and stored along with meta-data about it in the database. Users will be able to contribute snippets, linked articles and images to expand upon the generated documentation. {{attachment:updated_db_model.svg}} === Common Models === |
| Line 69: | Line 37: |
| ==== Distro ==== | ==== Distribution ==== |
| Line 75: | Line 43: |
| * '''website''' - URL to the distro's homepage | * '''url''' - URL to the distro's homepage |
| Line 78: | Line 46: |
| ==== DistroRelease ==== | ==== Release ==== |
| Line 83: | Line 51: |
| * '''distro''' - Foreign Key to a ''Distribution'' record | |
| Line 84: | Line 53: |
| * '''codename''' - Development codename for the release * '''release_date''' - Date when this was released * '''expiration_date''' - Date that support for the release ends |
* '''name''' - Development codename for the release * '''released''' - Date when this was released * '''expires''' - Date that support for the release ends |
| Line 98: | Line 67: |
| 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 |
This model is used to define a platform, it links API docs of a specific version to a specific Release * '''id''' - Auto-generated primary key * '''release''' - Foreign key to a ''!DistroRelease'' record |
| Line 104: | Line 72: |
| * '''packages''' - Comma-separated list of distro packages that provide this library === Support Models === |
* '''packages''' - List of distro packages that provide this library ==== Language ==== Will represent one of the available programming languages in the system * '''id''' - Auto-generated primary key * '''language_name''' - Name of the programming language * '''url''' - Optional URL for more information about the language === API Doc Models === These models contain the API docs themselves, pre-rendered to HTML by the import process. ==== Namespace ==== This model identifies a programming namespace for a collection of ''Element'' records * '''id''' - Auto-generated primary key * '''platform_item''' - Foreign key to ''!PlatformItem'' record * '''name''' - Name of the Namespace ==== Element ==== This model contains the pre-rendered HTML for an API element * '''id''' - Auto-generated primary key * '''namespace''' - Foreign key to a ''Namespace'' record * '''language''' - Foreign key to a ''Language'' record * '''name''' - Name of the Element * '''data''' - Pre-rendered HTML content for this api element === Search Models === These models contain searchable meta-data about the API elements ==== Class ==== This model contains information about a programming language class, it's methods and properties * '''id''' - Auto-generated primary key * '''rendered_element''' - Foreign key to an ''Element'' record * '''namespace''' - Foreign key to a ''Namespace'' record * '''name''' - Searchable name for this class * '''inherits''' - List of class names this one inherits from * '''member_names''' - List of member names * '''description''' - Searchable description * '''doc_string''' - Documentation provided in the code itself ==== BitField ==== This model contains information about a programming language bitfield and it's available field names * '''id''' - Auto-generated primary key * '''rendered_element''' - Foreign key to an ''Element'' record * '''namespace''' - Foreign key to a ''Namespace'' record * '''name''' - Searchable name for this class * '''field_names''' - List of field names * '''description''' - Searchable description * '''doc_string''' - Documentation provided in the code itself ==== Enum ==== This model contains information about a programming language enumeration and it's available value names * '''id''' - Auto-generated primary key * '''rendered_element''' - Foreign key to an ''Element'' record * '''namespace''' - Foreign key to a ''Namespace'' record * '''name''' - Searchable name for this class * '''enumerated_names''' - List of value names * '''description''' - Searchable description * '''doc_string''' - Documentation provided in the code itself === Related Models === |
| Line 111: | Line 149: |
| ==== 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 |
==== Link ==== Will link a tutorial or question on !AskUbuntu.com to an api element * '''id''' - Auto-generated primary key * '''rendered_element''' - Foreign key to an ''Element'' record * '''name''' - Short text of the link * '''link_type''' - Type of link, either Question or Tutorial * '''url''' - URL to the website with the target content ==== Snippet ==== Will contain short pieces of code demonstrating the use of an api element * '''id''' - Auto-generated primary key * '''rendered_element''' - Foreign key to an ''Element'' record * '''name''' - Short name of the code snippet * '''code''' - Long text field containing the full code snippet ==== Image ==== An uploaded image showing the visible result of an api element * '''id''' - Auto-generated primary key * '''rendered_element''' - Foreign key to an ''Element'' record * '''name''' - Short name or title of the image * '''caption''' - Short caption (one sentence) describing the image * '''url''' - URL to the image |
| Line 253: | Line 283: |
| || Import GIR doc strings || GIR Parser ||<#aaaaff>INPROGRESS || Current parser doesn't seem to include them || | || Import GIR doc strings || GIR Parser ||<#ffaaaa>TODO || Current parser doesn't seem to include them || |
| Line 259: | Line 289: |
| || !ProgrammingLang model || Data models ||<#ffaaaa>TODO || || || !LanguageNamespace model || Data models ||<#ffaaaa>TODO || || || Translator model || Data models ||<#ffaaaa>TODO || || || C Translator || Data models ||<#ffaaaa>TODO || Implement Translator for C || || C++ Translator || Data models ||<#ffaaaa>TODO || Implement Translator for C++ || || Python Translator || Data models ||<#ffaaaa>TODO || Implement Translator for Python || || Vala Translator || Data models ||<#ffaaaa>TODO || Implement Translator for Vala || || Distro model || Data models ||<#ffaaaa>TODO || || || !DistroRelease model || Data models ||<#ffaaaa>TODO || || |
|| Language model || Data models ||<#ffaaaa>TODO || || || Distribution model || Data models ||<#ffaaaa>TODO || || || Release model || Data models ||<#ffaaaa>TODO || || |
| Line 270: | Line 294: |
| || !RelatedQuestion model || Data models ||<#ffaaaa>TODO || || || !RelatedTutorial model || Data models ||<#ffaaaa>TODO || || || !RelatedSnippet model || Data models ||<#ffaaaa>TODO || || || !RelatedImage model || Data models ||<#ffaaaa>TODO || || |
|| Namespace model || Data models ||<#ffaaaa>TODO || || || Element model || Data models ||<#ffaaaa>TODO || || || Class model || Data models ||<#ffaaaa>TODO || || || BitField model || Data models ||<#ffaaaa>TODO || || || Enum model || Data models ||<#ffaaaa>TODO || || || Link model || Data models ||<#ffaaaa>TODO || || || Snippet model || Data models ||<#ffaaaa>TODO || || || Image model || Data models ||<#ffaaaa>TODO || || |
| Line 287: | Line 315: |
| || Linkify API items || Template Tags ||<#aaaaff>INPROGRESS || Try to match text against API items, making them links || |
Launchpad entry: https://launchpad.net/ubuntu-api-website
Created: 2012-06-28
Contributors: mhall119, jonobacon, john.vrbanac
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 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)
Data Model
The API data will be parsed from many different sources, pre-rendered into HTML, and stored along with meta-data about it in the database.
Users will be able to contribute snippets, linked articles and images to expand upon the generated documentation.
Common 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.
Distribution
This model will represent a reusable reference to a distro (Ubuntu, Kubuntu, Xubuntu, etc)
id - Auto-generated primary key
name - Name of the distribution
url - URL to the distro's homepage
description - Long text description of the distro
Release
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
distro - Foreign Key to a Distribution record
version - Official release version name or number
name - Development codename for the release
released - Date when this was released
expires - 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 API docs of a specific version to a specific Release
id - Auto-generated primary key
release - Foreign key to a DistroRelease record
section - Foreign ey to a PlatformSection record
packages - List of distro packages that provide this library
Language
Will represent one of the available programming languages in the system
id - Auto-generated primary key
language_name - Name of the programming language
url - Optional URL for more information about the language
API Doc Models
These models contain the API docs themselves, pre-rendered to HTML by the import process.
Namespace
This model identifies a programming namespace for a collection of Element records
id - Auto-generated primary key
platform_item - Foreign key to PlatformItem record
name - Name of the Namespace
Element
This model contains the pre-rendered HTML for an API element
id - Auto-generated primary key
namespace - Foreign key to a Namespace record
language - Foreign key to a Language record
name - Name of the Element
data - Pre-rendered HTML content for this api element
Search Models
These models contain searchable meta-data about the API elements
Class
This model contains information about a programming language class, it's methods and properties
id - Auto-generated primary key
rendered_element - Foreign key to an Element record
namespace - Foreign key to a Namespace record
name - Searchable name for this class
inherits - List of class names this one inherits from
member_names - List of member names
description - Searchable description
doc_string - Documentation provided in the code itself
BitField
This model contains information about a programming language bitfield and it's available field names
id - Auto-generated primary key
rendered_element - Foreign key to an Element record
namespace - Foreign key to a Namespace record
name - Searchable name for this class
field_names - List of field names
description - Searchable description
doc_string - Documentation provided in the code itself
Enum
This model contains information about a programming language enumeration and it's available value names
id - Auto-generated primary key
rendered_element - Foreign key to an Element record
namespace - Foreign key to a Namespace record
name - Searchable name for this class
enumerated_names - List of value names
description - Searchable description
doc_string - Documentation provided in the code itself
Related Models
The frontend will have a number of Django models specific to Ubuntu, making use for the GDN data models.
Link
Will link a tutorial or question on AskUbuntu.com to an api element
id - Auto-generated primary key
rendered_element - Foreign key to an Element record
name - Short text of the link
link_type - Type of link, either Question or Tutorial
url - URL to the website with the target content
Snippet
Will contain short pieces of code demonstrating the use of an api element
id - Auto-generated primary key
rendered_element - Foreign key to an Element record
name - Short name of the code snippet
code - Long text field containing the full code snippet
Image
An uploaded image showing the visible result of an api element
id - Auto-generated primary key
rendered_element - Foreign key to an Element record
name - Short name or title of the image
caption - Short caption (one sentence) describing the 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.
Initial PlatformSections for Ubuntu are:
- System
- Desktop
- Multimedia
- User Accounts
- Online Services
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). A quick reference list of all the classes, enums and top-level functions is displayed on the left-hand side.
Class Page
When a user clicks on a class we see the class information page. This page has a number of features:
- The page is broken into sections, links to each section are displayed at the top of the page.
- The class definition, heirarchy and an example screenshot (of relevant) are displayed first
- The API (constructors, methods, signal and properties) are shown below the class definition
- This reference content is displayed for the appropriately selected language (the language selector is at the top of all pages).
Sections for code snippets, tutorials and AskUbuntu questions are displayed below the API, with links for submitting additional content for those sections
- We would enable Disqus commenting on each page too.
- The quick reference list of classes, enums and top-level functions remains available on the left-hand side.
Search Results Page
TODO: Define this 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
import-gir
Given a .gir file, import its data into the database. If a previous version of the same namespace if specified, forward copy all related records (snippets, tutorials, questions and comments.
import-qt
Given a Qt library XML file, import its data into the database. If a previous version of the same namespace if specified, forward copy all related records (snippets, tutorials, questions and comments.
create-release
Given a distro and previous release, create a new release record and forward-copy the previous release's platform items to it.
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.
Work Items
Item |
Section |
Status |
Notes |
Management |
|||
Import GIR doc strings |
GIR Parser |
TODO |
Current parser doesn't seem to include them |
Import Qt API metadata |
Qt Parser |
TODO |
Need to identify what format we can get this data in |
import-gir command |
GIR Parser |
TODO |
Needs to process all .gir files in a directory |
import-qt command |
Qt Parser |
TODO |
Needs to process all Qt metadata docs in a directory |
create-release command |
Release Management |
TODO |
Needs to forward-copy platform defintions |
Backend (Django) |
|||
Language model |
Data models |
TODO |
|
Distribution model |
Data models |
TODO |
|
Release model |
Data models |
TODO |
|
PlatformSection model |
Data models |
TODO |
|
PlatformItem model |
Data models |
TODO |
|
Namespace model |
Data models |
TODO |
|
Element model |
Data models |
TODO |
|
Class model |
Data models |
TODO |
|
BitField model |
Data models |
TODO |
|
Enum model |
Data models |
TODO |
|
Link model |
Data models |
TODO |
|
Snippet model |
Data models |
TODO |
|
Image model |
Data models |
TODO |
|
Index view |
Views |
TODO |
Provide a list of active Distro records |
Distro view |
Views |
TODO |
Provide a list of active DistroRelease records for a distro |
Release view |
Views |
TODO |
Provide a list of PlatformItems, grouped by PlatformSection, plus tutorials and questions for a release |
Class view |
Views |
TODO |
Provide class, methods, signals, properties, questions, tutorials, snippets and images |
Search view |
Views |
TODO |
Provide a list of classes, methods, signals or properties that match a search term |
Text editing |
Views |
TODO |
Accept data submitted from inline text editing |
Frontend (HTML/CSS) |
|||
Base template |
Templates |
INPROGRESS |
Use ubuntu-community-webthemes (See mockups) |
Index template |
Templates |
TODO |
List all Distros with links to their Distro page (See mockups) |
Distro template |
Templates |
TODO |
List all DistroReleases with links to their Release page (See mockups) |
Release template |
Templates |
TODO |
Group Namespaces by section, providing links for each supported language (See mockups) |
Class template |
Templates |
TODO |
(See mockups) |
Search template |
Templates |
TODO |
(See mockups) |
Text editing |
Scripting |
TODO |
Allow inline text editing for those with permission |
Images display |
Scripting |
TODO |
Provide a popup/lightbox for viewing multiple images |
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
DeveloperNetwork (last edited 2013-05-27 17:36:58 by mhall119)