[debexpo-devel] debexpo documentation / sphinx?
Jonny Lamb
jonnylamb at jonnylamb.com
Tue May 6 13:00:42 CEST 2008
[Sending to the list as this is not private at all, although this is
probably a very boring thread to others! Also CC'ing to Christoph just
to point out I'm using the list; I don't intend to continue CC'ing him.]
On Fri, May 02, 2008 at 05:39:20PM +0200, Christoph Haas wrote:
> On Freitag, 2. Mai 2008, Jonny Lamb wrote:
> > Perhaps I don't understand your intentions, but Sphinx seems to be
> > oriented around user, hand-written, docs, as opposed to auto-generated
> > API documentation.
>
> I haven't used it in-depth yet. But it seems to do both. As far as I
> understand it Sphinx creates API documentation (epydoc/doxygen style) and
> also custom .rst files in a different directory than where your code
> lives. So besides the automatic code documentation from the docstrings it
> seems that Sphinx allows to write RST-style files that are made into
> searchable web pages. And from the RST files you can refer to the API
> which is turned into links to the API documentation.
Okay, so I've just been playing with Sphinx, and yes it creates pretty
docs from .rst files you write, in many formats. It does not seem to
produce any output from looking at code though. Sphinx's own API docs
(E.g. [0]) appear hand-written. So, unless I'm being silly (and please
show me if I am), Sphinx isn't really for that task.
However, I really do like the documentation I can make Sphinx produce.
It looks smart and is easy to make. It would be nice to set up the user
docs in this way.
I'm not up for big long tutorials inline with the code, but I am after
something simple above a function declaration that outlines what each
parameter is, and what it returns. This need not be transferred into
anything like HTML like the user docs as it's not a library and won't
need referring to in such a concrete way..
Is it clear what I mean? Am I being unreasonable?! :-)
Anyway, getting too carried away on documentation discussion is
worrying! On another note, I've been messing with Pylons recently and
getting to know it more. I'm not overly familiar with Pylons+SQLAlchemy
yet, but I'll find some time to write some small-ish app to make sure I
understand it all, and am doing it in a Pylons-esque way.
I then still have the task of creating the required tickets and
milestones on Trac. (Have I got privileges to use trac-admin?) Exams are
hotting up around now, but I'm sure I'll have some time for this.
Regards,
0. http://sphinx.pocoo.org/ext/appapi.html
--
Jonny Lamb, UK jonnylamb at jonnylamb.com
http://jonnylamb.com GPG: 0x2E039402
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://workaround.org/pipermail/debexpo-devel/attachments/20080506/b1ee6f57/attachment.pgp
More information about the debexpo-devel
mailing list