#104: Updated API reference toolchain
----------------------------------+-----------------------------------------
Reporter: [EMAIL PROTECTED] | Owner: anonymous
Type: enhancement | Status: new
Priority: normal | Milestone: 0.9
Component: Docs | Version: 0.8
Severity: normal | Resolution:
Keywords: |
----------------------------------+-----------------------------------------
Changes (by kevin):
* type: defect => enhancement
* summary: Some functions missing from TG API reference => Updated API
reference toolchain
Old description:
> When looking for documentation on the function turbogears.url(), I did
> not find them in the online API documentation. The docstrings are there,
> however, as opening a shell and entering:
>
> >>> import turbogears
> >>> help(turbogears.url)
>
> ... will yield the docstring.
>
> Kevin suspects a configuration error.
New description:
I would like to generate API docs using either Epydoc or PythonDoc (which
both support attaching metadata about specific aspects of methods and
source parsing, which allows documentation for object properties). I also
really like having links to syntax highlighted source files, as Pudge
provides or the current hacked epydoc provides.
PythonDoc has the advantage in that it creates an infoset based on the
data it collects. This makes it relatively easy to format things however
we want. It currently has a limitation that it doesn't parse out the
metadata tags from the docstrings, just from doc comments. I really want
our docs in docstrings so that things like pydoc and help() work properly.
I'm not fond of Epydoc's multiframe appearance, and I don't think anyone
else really is either. You can turn off the frames and adjust the CSS, and
that may be enough customization.
So, the challenge here is to pick one of those two tools (Epydoc 3 or
PythonDoc) and then figure out the magic incantations/create templates and
CSS to generate the API docs for TurboGears and everything in thirdparty
except MochiKit.
--
Ticket URL: <http://trac.turbogears.org/turbogears/ticket/104>
TurboGears <http://www.turbogears.org/>
TurboGears front-to-back web development
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TurboGears Tickets" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/turbogears-tickets
-~----------~----~----~----~------~----~------~--~---
