Task:Publishing API docs

m
 
Line 2: Line 2:
{{task|proposed}}
{{task|proposed}}
-
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 rame would be the Fremantle release cycle.
+
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.
-
==Tasks==
+
==Requirements==
-
We can split the work in three loads adaptable to sprints:
+
 
 +
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
===Plan===
===Plan===
-
* Recover the useful information from the previous discussions - Ferenc knows.
+
* Get external library.maemo.org working
-
* Have a look at the best practices around. e.g. http://library.gnome.org - what else.
+
** Install library.gnome.org and get it working with .debs in a Debian repository rather than building documentation with a .tar.gz
-
* Agree on what we want for maemo.org.
+
** 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
-
===Tool & Process===
+
After the initial task, there are other issues to resolve:
-
* Define the process.
+
-
* Get the commitment from Nokia.
+
-
* Implement the tool.
+
-
===Release===
+
* Ensure that Doxygen, gtk-doc and qdoc documentation are all consistent in terms of stylesheets & layout
-
* Real content needs to land.
+
* Probably others I haven't thought of right now
-
* Test, debug, fine tune.
+
-
* Final release.
+

Latest revision as of 13:49, 19 June 2009

Image:Ambox_notice.png
 This article is continued discussion from the maemo.org brainstorm
Please see the 2010 Agenda for more.
Image:Ambox_notice.png
 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
Retrieved from "https://wiki.maemo.org/Task:Publishing_API_docs"