Task:Publishing API docs

This article is continued discussion from the maemo.org brainstorm
Please see the 2010 Agenda for more.
This task is in the list of maemo.org development proposals, please help planning and getting it ready for a sprint. Put a note on the talk page if you're interested in helping work on this task.
Please see the talk page for discussion.

Currently the API docs are spread in different spaces and are processed through different tools. We need a unified process and a single place. This task needs to be done in collaboration with the Nokia teams. The ideal time frame would be the Fremantle release cycle.

[edit] Requirements

An API doc publishing system should fulfill a few basic requirements:

  • Automated: When a new version of a package is released, the API documentation should be updated accordingly, with no human intervention
  • Searchable: You should be able to search API docs by function name, or by task (free text)
  • Complete: All API references should be documented, and be up to date.
  • Works internally & externally: Unreleased APIs should have in-progress API documentation visible on the Nokia intranet, released packages should have their API documentation automatically updated on an external site

[edit] Plan

  • Get external library.maemo.org working
    • Install library.gnome.org and get it working with .debs in a Debian repository rather than building documentation with a .tar.gz
    • Ensure it detects new releases and rebuilds documentation automatically
    • Set it loose on Maemo's repository with a starting module list
    • Work on look & feed of front page to ensure it integrates well with the rest of maemo.org
  • Get internal library working
    • Manage internal releases, define repository for in-progress API docs

After the initial task, there are other issues to resolve:

  • Ensure that Doxygen, gtk-doc and qdoc documentation are all consistent in terms of stylesheets & layout
  • Probably others I haven't thought of right now