The API docs should have a table of contents
Bug #325367 reported by
Māris Fogels
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.
Related branches
lp:~geser/launchpadlib/toc
Merged
into
lp:launchpadlib
- Curtis Hovey (community): Approve (code)
- Diff: None lines
Changed in launchpadlib: | |
status: | Fix Committed → Fix Released |
To post a comment you must log in.
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