##(see the SpecSpec for an explanation) * '''Launchpad entry''': https://launchpad.net/ubuntu-api-website * '''Created''': 2012-06-28 * '''Contributors''': [[LaunchpadHome:mhall119]], [[LaunchpadHome:jonobacon]], [[LaunchpadHome: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 qdoc and save it in discrete fields in a database * Display API in multiple programming languages (C++, QML/Javascript) * Allow searching the API fields * Allow multiple versions of the same API (Qt 5.0, Qt 5.1, 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. {{attachment:updated_db_model.svg}} === 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 ''PlatformItem''s 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 using Django templates, wrapping the pre-rendered HTML for each API element with a standard header, footer and other navigation. === Theme === This project should use the [[https://launchpad.net/ubuntu-community-webthemes/light-django-theme|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 and Element name: * /api/ubuntu/12.04/python /Unity/LauncherEntry/ * /api/ubuntu/12.04/c /Unity/LauncherEntry/ Views should contain anchor links to all API elements on the page: * /api/ubuntu/12.04/python/Unity/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 !DistroRelease records. This list will contain only supported releases (those that have not reached their ''expiration_date'') ordered by ''release_date'', with an associated screenshot. {{attachment:main.png}} === 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. {{attachment:release.png}} 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. {{attachment:gtk.png}} === Element Page === When a user clicks on a class, enum or bitfield we see the 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. {{attachment:dialog.png}} === Search Results Page === ||<#ffaaaa>'''TODO:''' Define this page || {{attachment:search.png}} == 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: {{http://farm9.staticflickr.com/8009/7463069484_05f7981be3_b.jpg}} The site would support markdown format to make it easy for users to edit and submit content. == Management Commands == === import-qt === Given a Qt library XML file (qdoc DITA output), 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 QML, she wants to lookup specific QML components 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''' || ||<-4 #eeeeee>Management || || Import Qt API metadata || Qt Parser ||<#ffaaaa>TODO || Need to identify what format we can get this data in || || import-qt command || Qt Parser ||<#ffaaaa>TODO || Needs to process all Qt metadata docs in a directory|| || create-release command || Release Management ||<#ffaaaa>TODO || Needs to forward-copy platform defintions || ||<-4 #eeeeee>Backend (Django) || || Language model || Data models ||<#aaffaa>DONE || || || Distribution model || Data models ||<#aaffaa>DONE || || || Release model || Data models ||<#aaffaa>DONE || || || !PlatformSection model || Data models ||<#aaffaa>DONE || || || !PlatformItem model || Data models||<#aaffaa>DONE || || || Namespace model || Data models ||<#aaffaa>DONE || || || Element model || Data models ||<#aaffaa>DONE || || || Class model || Data models ||<#aaffaa>DONE || || || BitField model || Data models ||<#aaffaa>DONE || || || Enum model || Data models ||<#aaffaa>DONE || || || Link model || Data models ||<#aaffaa>DONE || || || Snippet model || Data models ||<#aaffaa>DONE || || || Image model || Data models ||<#aaffaa>DONE || || || Index view || Views ||<#ffaaaa>TODO || Provide a list of active Distro records || || Distro view || Views ||<#ffaaaa>TODO || Provide a list of active !DistroRelease records for a distro|| || Release view || Views ||<#ffaaaa>TODO || Provide a list of !PlatformItems, grouped by !PlatformSection, plus tutorials and questions for a release|| || Element view || Views ||<#ffaaaa>TODO || Provide class, methods, signals, properties, questions, tutorials, snippets and images|| || Search view|| Views ||<#ffaaaa>TODO || Provide a list of classes, methods, signals or properties that match a search term || || Text editing || Views ||<#ffaaaa>TODO || Accept data submitted from inline text editing || ||<-4 #eeeeee>Frontend (HTML/CSS)|| || Base template || Templates ||<#aaaaff>INPROGRESS || Use ubuntu-community-webthemes (See mockups) || || Index template || Templates ||<#ffaaaa>TODO || List all !DistroReleases with links to their Release page (See mockups) || || Release template || Templates ||<#ffaaaa>TODO || Group Namespaces by section, providing links for each supported language (See mockups) || || Class template || Templates ||<#ffaaaa>TODO || (See mockups) || || Search template || Templates ||<#ffaaaa>TODO || (See mockups) || || Text editing || Scripting ||<#ffaaaa>TODO || Allow inline text editing for those with permission || || Images display || Scripting ||<#ffaaaa>TODO || Provide a popup/lightbox for viewing multiple images || == Unresolved issues == ---- CategorySpec