[debexpo-devel] debexpo documentation / sphinx?

Christoph Haas email at christoph-haas.de
Tue May 6 14:29:57 CEST 2008


On Dienstag, 6. Mai 2008, Jonny Lamb wrote:
> [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.]

[/disclaimer]    :)

> Okay, so I've just been playing with Sphinx, and yes it creates pretty
> docs from .rst files you write, in many formats.

Which is what rst2html and all the other tools from python-docutils 
probably also do.

> It does not seem to 
> produce any output from looking at code though. Sphinx's own API docs
> (E.g. [0]) appear hand-written.

I believe that Sphinx created that documentation indeed.

> So, unless I'm being silly (and please 
> show me if I am), Sphinx isn't really for that task.

Well, I'll probably use Shinx for a (closed-source) software I'm working on 
to get a better feel for it. And I'll be contributing to the Pylons 
documentation. Perhaps I can report about the benefits of Sphinx later 
when we decided for something else. :) From what I have seen it's a good 
way to create both user and API docs in a pretty way while allowing 
cross-referencing. I'll see.

But it's entirely up to you. I don't mean to bore you to death with any 
stupid software I stumble upon. :) Just pick what you like. I think it's 
obvious we need some kind of documentation in the end. How it will look 
exactly shouldn't bother me too much. I rest my case.

> 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.

Seconded.

> Is it clear what I mean? Am I being unreasonable?! :-)

Not at all. User documentation doesn't belong into the code. It's two 
things. My original argument was that it might be nice to offer both API 
and user docs generated automatically (e.g. by Sphinx). That would have 
meant that there are documents containing a hand-written part. And on the 
other hand the docstrings from the code. Sphinx would have have been a 
mean to join both parts "under one umbrella".

> 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.

Fine. Allow me to point you to 
http://workaround.org/pylons/pylons-cheatsheet.html#database-access. It's 
not entirely up-to-date but might give some ideas on how accessing 
object-relationally-mapped objects through SQLAlchemy looks like and what 
the "Session" is. It took me quite some time to get a grab. So don't 
hesitate to ask if I may know the answer. :)

> I then still have the task of creating the required tickets and
> milestones on Trac. (Have I got privileges to use trac-admin?) 

You should. Please try "trac-admin /home/www/debexpo.workaround.org".

> Exams are 
> hotting up around now, but I'm sure I'll have some time for this.'

First things first. And I don't mean "debexpo" as "first". :)

Cheers
 Christoph
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://workaround.org/pipermail/debexpo-devel/attachments/20080506/b8d2b0a7/attachment.pgp 


More information about the debexpo-devel mailing list