The API docs should have a table of contents

Bug #325367 reported by Māris Fogels
18
This bug affects 1 person
Affects Status Importance Assigned to Milestone
launchpadlib
Fix Released
Medium
Leonard Richardson

Bug Description

The auto-generated API documentation should have a high-level table of contents.

Right now, I have to manually search the large, long document to see if a particular entity I want, or something like it, has been published.

2 levels should be all that's necessary:

* Top Level Collections
  - bugs
  - cves
  ....
* Entry Types
  - archive
  - archive_permission

A "top" link in each section would also be useful, so I can quickly get back to the Table of Contents if what I found isn't what I want.

Tags: api

Related branches

Revision history for this message
Markus Korn (thekorn) wrote :

I agree, as more and more methods are added to the API, this api-doc needs a better structure with a TOC and maybe a search-index.

What about using a framework like sphinx [0] for this? This needs a xsl style-sheet to convert the wadl definition to reStructuredText. This stylesheet can also be used to create __doc__ entries for each method, so that e.g. help(launchpad.bugs) prints some useful help text instead of the docstring of all collections-objects.

Markus

[0] http://sphinx.pocoo.org

Changed in launchpadlib:
status: New → Confirmed
Revision history for this message
Markus Korn (thekorn) wrote :

I just started to play with sphinx a bit, the hardest part seems to be to create a wadl->rst stylesheet.
My first results are here: lp:~thekorn/launchpadlib/documentation, to read the documentation open build/html/index.html

Revision history for this message
Leonard Richardson (leonardr) wrote :

It looks like you're talking about two different things.

1. Add a TOC to the generated HTML.
2. Retrieve values for __doc__ for generated objects and methods so that documentation info is available from an interactive shell.

I've filed bug 364198 for #2. This bug is now solely about #1.

Changed in launchpadlib:
importance: Undecided → Medium
status: Confirmed → Triaged
Revision history for this message
Bryce Harrington (bryce) wrote :

A lot of new stuff has been added to the document in recent months, and even though I'm pretty familiar with the document overall, navigating it without a TOC has gotten pretty painful. Please up the priority on this; it's only going to get worse...

Revision history for this message
Jonathan Lange (jml) wrote :

I had a chat with Karl about this earlier today. He suggested that it would probably be an easy fix for Leonard...

Changed in launchpadlib:
assignee: nobody → Leonard Richardson (leonardr)
Revision history for this message
Karl Fogel (kfogel) wrote :

I misled about Leonard -- though a guru about many things, it turns out he's not an xslt guru. My bad. But Curtis Hovey apparently is, and Markus Korn might be one by now given his branch. Pinging him now in IRC.

Note: bug #426323 ("put title attributes on section/div elements in API documentation") is likely to involve similar knowledge.

Revision history for this message
Karl Fogel (kfogel) wrote :

geser's merge proposal solves this: https://code.edge.launchpad.net/~geser/launchpadlib/toc/+merge/11398

Marking as "in progress" until reviewed.

Changed in launchpadlib:
status: Triaged → In Progress
Revision history for this message
Karl Fogel (kfogel) wrote :

Committed to lp:launchpadlib trunk in r55.

Changed in launchpadlib:
status: In Progress → Fix Committed
Changed in launchpadlib:
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Duplicates of this bug

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.