API generation is ready for tg2
gas...@gmail.com
I made a doc/ folder on tg2/ to handle the API generation stuff, and
make some modification on module doc strings.
At this moment you could easily generate tg2 APi with epydoc.
There's also a README for API generation instructions :)
Document generation Guide
=========================
You need to install epydoc 3 first before go through this doc.
You could got epydoc source from epydoc svn::
$ svn co https://svn.sourceforge.net/svnroot/epydoc
And follow epydoc's doc to install it.
Check Modules
-------------
To check what docs need to be written, use the command in source
folder::
$ epydoc --check tg
The command will gather all undocumented and no description python
methods.
Generate Docs
-------------
To generate Turbogears2 API, use the command in source folder::
$ epydoc --config doc/doc.ini
to generate API documents into tg2/apidoc folder.
You could custom the doc.ini setting to generate other type of docs.
Write Docs
----------
Note in TurboGears 2 we use reStructuredText format for doc strings
It's a bit different from epydoc's default format.
Check docs about reStructuredText format on epydoc site.
http://epydoc.sourceforge.net/manual-docstring.html
http://epydoc.sourceforge.net/manual-othermarkup.html
http://epydoc.sourceforge.net/manual-fields.html
Debug Docs
-----------
To find where the format error is, use command::
$ epydoc --config doc/doc.ini -v
Ian Bicking
> I made a doc/ folder on tg2/ to handle the API generation stuff, and
> make some modification on module doc strings.
>
> At this moment you could easily generate tg2 APi with epydoc.
>
> There's also a README for API generation instructions :)
>
>
> Document generation Guide
> =========================
>
> You need to install epydoc 3 first before go through this doc.
>
> You could got epydoc source from epydoc svn::
>
> $ svn co https://svn.sourceforge.net/svnroot/epydoc
>
> And follow epydoc's doc to install it.
They have a Makefile? Wow, that's very retro. And weird.
> Check Modules
> -------------
>
> To check what docs need to be written, use the command in source
> folder::
>
> $ epydoc --check tg
>
> The command will gather all undocumented and no description python
> methods.
>
> Generate Docs
> -------------
>
> To generate Turbogears2 API, use the command in source folder::
>
> $ epydoc --config doc/doc.ini
>
> to generate API documents into tg2/apidoc folder.
>
> You could custom the doc.ini setting to generate other type of docs.
It would be nice if you could do "python setup.py epydoc" in TG, reading
config settings from setup.cfg. If anyone is inclined towards such
things, the glue code is pretty small. But you have to use distutils
command line framework, which is a tad crufty (but not that bad,
really). Anyway, if anyone is curious about such things, I can point
you to example code.
--
Ian Bicking | ia...@colorstudy.com | http://blog.ianbicking.org
| Write code, do good | http://topp.openplans.org/careers
Jonathan LaCour
> I made a doc/ folder on tg2/ to handle the API generation stuff, and
> make some modification on module doc strings.
Cool, this is a good start, but epydoc produces some narsty looking
docs. I wonder if we might be able to take advantage of Georg Brandl's
work on enhancing the Python standard library documentation:
http://mail.python.org/pipermail/python-dev/2007-May/073232.html
The generated docs look gorgeous, and it would be nice if we could
fit into the general look and feel of the Python standard library
documentation.
--
Jonathan LaCour
http://cleverdevil.org
Noah Gift
Cool, this is a good start, but epydoc produces some narsty looking
docs. I wonder if we might be able to take advantage of Georg Brandl's
work on enhancing the Python standard library documentation:
http://mail.python.org/pipermail/python-dev/2007-May/073232.html
The generated docs look gorgeous, and it would be nice if we could
fit into the general look and feel of the Python standard library
documentation.
Ian Bicking
It's his own code. I don't think he's done any release, but I think the
code is out there somewhere if you look in the doc-sig lists. This is
the codebase that I think we (Paste, Pylons) would be most interested in
pursuing. I've thought about epydoc, and while I'm not opposed to it,
it's not terribly appealing. You have to tweak things a lot to get
something nice (no frames, better stylesheet, etc), and I don't think it
has anything for stand-alone documentation. And I definitely want a
toolset that does both generated and hand-written docs, with crosslinking.
Jonathan LaCour
>> The generated docs look gorgeous, and it would be nice if we could
>> fit into the general look and feel of the Python standard library
>> documentation.
>
> That does look good...what tool did he use to do that?
From what I can tell, its a tool of his own creation. I might send him
and email and find out if I can get access to the code somehow, and if
it might be usable for TurboGears.
In my opinion, Python is really lacking a good documentation system, and
Georg's work looks like it might be the thing to solve that problem.
If we can find a way to use it, maybe we can blaze a trail for other
projects.
Noah Gift
> That does look good...what tool did he use to do that?
From what I can tell, its a tool of his own creation. I might send him
and email and find out if I can get access to the code somehow, and if
it might be usable for TurboGears.
In my opinion, Python is really lacking a good documentation system, and
Georg's work looks like it might be the thing to solve that problem.
If we can find a way to use it, maybe we can blaze a trail for other
projects.
code is out there somewhere if you look in the doc-sig lists. This is
the codebase that I think we (Paste, Pylons) would be most interested in
pursuing. I've thought about epydoc, and while I'm not opposed to it,
it's not terribly appealing. You have to tweak things a lot to get
something nice (no frames, better stylesheet, etc), and I don't think it
has anything for stand-alone documentation. And I definitely want a
"
Lets be careful here guys...two python web application frameworks have just merged, and next we are talking about fixing globally python documentation generation....these are dangerous ideas, from dangerous subversive minds........in other words keep up the good work. Next thing you know someone is going to fork django and make it wsgi compatible :)
gas...@gmail.com
> Lets be careful here guys...two python web application frameworks have just
> merged, and next we are talking about fixing globally python documentation
> generation....these are dangerous ideas, from dangerous subversive
> minds........in other words keep up the good work. Next thing you know
> someone is going to fork django and make it wsgi compatible :)
>
The things we all agree is we should document modules with RST format.
Then we could generate API with whatever API generation tools.
At this time epydoc is the first candidate, and it works :)
The tool Ian mentioned is here:
http://svn.berlios.de/svnroot/repos/docutils/trunk/sandbox/py-rest-doc/
(following the discussion on http://mail.python.org/pipermail/python-dev/2007-May/073259.html)
That tool has a makefile, too :p
It's a DOC generation tool but not an API generation tool.
So it may not suite for our API generation case.
Christopher Arndt
> The tool Ian mentioned is here:
> http://svn.berlios.de/svnroot/repos/docutils/trunk/sandbox/py-rest-doc/
> (following the discussion on http://mail.python.org/pipermail/python-dev/2007-May/073259.html)
>
> So it may not suite for our API generation case.
And if we were to think about any other (non-API) documentation tool
(not that I think that we should) we must think about a way to migrate
what's already in the wiki. Unless we want to start docs for 1.1/2.0
totally from scratch.
IMHO any technical solution can only take the pain out of the
documentation effort so much. In the end, you just have set some time
aside and *write that documentation*.
Regarding the API-doc generation, I second Noah's sentiment. Don't get
to fancy, choose a tool, that produces a usable output and when you've
got that working *then* you can think about improving it.
Chris
Chris Miles
On 29 Jun 2007, at 20:26, gas...@gmail.com wrote:
>
> The things we all agree is we should document modules with RST format.
>
> Then we could generate API with whatever API generation tools.
> At this time epydoc is the first candidate, and it works :)
>
I don't mind the Twisted API docs - http://twistedmatrix.com/
documents/current/api/ - they are generated by PyDoctor which appears
to support RST in the docstrings.
http://codespeak.net/~mwh/pydoctor/
Cheers
Chris Miles
Mark Ramm
> config settings from setup.cfg. If anyone is inclined towards such
> things, the glue code is pretty small. But you have to use distutils
> command line framework, which is a tad crufty (but not that bad,
> really). Anyway, if anyone is curious about such things, I can point
> you to example code.
For now I think we're still exploring all our options. Epydoc seems
to just work right now, which is a huge benefit, but some of the other
options will give more control over the output format, which I think
is a good thing.
It would also be great to see something that TG+Pylons+Paste could
standardize on.
I really don't know what we should do ultimately, but I think we
should continue to explore our options for a couple weeks at least.
--Mark