[Twisted-Python] API reference
Hi everyone, The new website seems to be coming along nicely. However, I find myself missing the old API reference a lot. The previous Javadoc style reference was very easy to navigate, jump across things, and provided a lot more useful information in the same screen space compared to the current format (where everything is on its own HTML page, no frames) It seems the pages are still being generated by epydoc -- some styling is missing, and the frames page is missing? Is this something being worked on/considered? Or is the current format of API reference final? Thanks, Diwaker -- Web/Blog/Gallery: http://floatingsun.net/blog
On Sun, 5 Mar 2006 12:00:30 -0800, Diwaker Gupta
Hi everyone,
The new website seems to be coming along nicely. However, I find myself missing the old API reference a lot. The previous Javadoc style reference was very easy to navigate, jump across things, and provided a lot more useful information in the same screen space compared to the current format (where everything is on its own HTML page, no frames)
It seems the pages are still being generated by epydoc -- some styling is missing, and the frames page is missing? Is this something being worked on/considered? Or is the current format of API reference final?
The documentation is being generated by mwh's docextractor project. It is very much a work in progress. And speaking of which, I've just updated the website with a version of the html which includes some significant style improvements from jml and mwh. Further suggestions for improvements are welcome. Jean-Paul
The documentation is being generated by mwh's docextractor project. It is very much a work in progress. And speaking of which, I've just updated the website with a version of the html which includes some significant style improvements from jml and mwh. Further suggestions for improvements are welcome.
The new pages look better (color/styles etc help in quickly going over documentation), but I still find myself losing a lot of context flipping back and forth between pages. I find the Javadoc style frame-based documentation much more productive. Just my 2c. Diwaker -- Web/Blog/Gallery: http://floatingsun.net/blog
I agree, the old documentation was better. The thing that I miss the most is
the search, that would be restricted to Docs only, rather than the site-wide
search.
-----Original Message-----
From: twisted-python-bounces@twistedmatrix.com
[mailto:twisted-python-bounces@twistedmatrix.com] On Behalf Of Jean-Paul
Calderone
Sent: Sunday, March 05, 2006 3:25 PM
To: Twisted general discussion
Subject: Re: [Twisted-Python] API reference
On Sun, 5 Mar 2006 12:00:30 -0800, Diwaker Gupta
Hi everyone,
The new website seems to be coming along nicely. However, I find myself missing the old API reference a lot. The previous Javadoc style reference was very easy to navigate, jump across things, and provided a lot more useful information in the same screen space compared to the current format (where everything is on its own HTML page, no frames)
It seems the pages are still being generated by epydoc -- some styling is missing, and the frames page is missing? Is this something being worked on/considered? Or is the current format of API reference final?
The documentation is being generated by mwh's docextractor project. It is very much a work in progress. And speaking of which, I've just updated the website with a version of the html which includes some significant style improvements from jml and mwh. Further suggestions for improvements are welcome. Jean-Paul _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
"Diwaker Gupta"
Hi everyone,
The new website seems to be coming along nicely. However, I find myself missing the old API reference a lot. The previous Javadoc style reference was very easy to navigate, jump across things,
Strange, I always find epydoc output pretty hard to navigate... [...]
It seems the pages are still being generated by epydoc
Nope. epytext, epydoc's markup system is used by the docstrings though, so we still use epydoc's parser/formatter for that.
-- some styling is missing, and the frames page is missing? Is this something being worked on/considered?
It's being worked on fairly actively: http://codespeak.net/svn/user/mwh/docextractor/trunk/
Or is the current format of API reference final?
Hardly! In addition to what JP said, concrete suggestions on how to improve it or even patches are very welcome. I sometimes have a more up-to-date/experimental version up at: http://starship.python.net/crew/mwh/apidocs/twisted.html (it's only mildly different from what's on twistedmatrix.com right now). Cheers, mwh -- The source passes lint without any complaint (if invoked with
/dev/null). -- Daniel Fischer, http://www.ioccc.org/1998/df.hint
participants (4)
-
Alec Matusis -
Diwaker Gupta -
Jean-Paul Calderone -
Michael Hudson