[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