[debexpo-devel] debexpo documentation / sphinx?

Jonny Lamb jonnylamb at jonnylamb.com
Tue May 6 21:05:49 CEST 2008


On Tue, May 06, 2008 at 02:29:57PM +0200, Christoph Haas wrote:
> 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.
[snip]
> 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".

Right, well, it turns out I was indeed being silly and not understanding
how Sphinx properly works. I understand better now and I have the
autodocumenting working fine now. It's nice, except they certainly don't
make it easy for newcomers to work out how to use it though. Oh well, I
think I've pretty much figured it out now. Now I only need to learn
ReST!

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

Cool, thanks. [0] is on my reading TODO list at the moment.

0. http://docs.pythonweb.org/display/pylonsdocs/Using+SQLAlchemy+with+Pylons

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

Cool, that works. Thanks.

Regards,

-- 
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/878f9f04/attachment.pgp 


More information about the debexpo-devel mailing list