Hi!
Tess Chu wrote:
Zero, have you looked at Sphinx vs. other documentation tools? Do you
have any pointers as to whether it's appropriate for our use? We're
using Oxygen for documentation of OGP.
There is also http://xml.resource.org/ which converts documents written
a la http://www.faqs.org/rfcs/rfc2629.html
E.g. OAuth, XRDS-Simple and the portablcontacts spec are written using
this. An example output is here: http://xrds-simple.net/core/1.0/
See the portablecontacts source here:
http://portablecontacts.googlecode.com/svn/spec/core/1.0/drafts/1/spec.xml
(At least I think it's xml2rfc used there. But as it's XML you can also
transfer it to any other format anyway).
Then again when looking at that source, ReST syntax looks easier ;)
What would be cool for commenting would be something like the Djangobook
does though:
http://www.djangobook.com/about/comments/
Unfortunately this seems not to be open source. There are other services
like this out there but I think this one is really quite simple.
The best might be to be able to convert this RFC style format to
something like the djangobook version and it would be even better if
some editor would be included for also incorporating these comments
directly.. But I guess such a solution is not directly available ;-)
Just some brainstorming..
-- Christian
Thanks,
Tess
Christian Scholz wrote:
Hi!
I've Updated PJira Issue PYO-3 (
http://jira.secondlife.com/browse/PYO-3 )
so that it's easier for you to track, add and work on Documentation
'Issues'
outlined here -
https://wiki.secondlife.com/wiki/User:Enus_Linden/Project-Wiki-Structure
This way all of the 'issues' are separate and can be Updated,
assigned and
Resolved that way.
Hopefully this will lighten your load slightly and make things a little
easier for you! : D
It makes at least clearer what the load is so thanks for organizing
it! :)
I also discussed with Enus yesterday if we maybe should use Sphinx for
documentation. It is reStructured text based and rather easy to write.
The docs will reside on the filesystem and thus in svn which makes
them also versioned which is good I think.
They can also contain example code in doctest format so that we can
even automatically test the documentation and get informed if it does
not match the code anymore. I think it also might make it easier to
stay in one place and be exported from there. At least for me it makes
it more likely to write documentation as it's also faster than editing
a wiki.
Sphinx moreover allows for various output generators like HTML, PDF
and others (maybe there is even a mediawiki extension).
I made a little example here: http://pyogp.net/html
(and btw, there is a docs/ directory in pyogp.lib.base by default
anyway which would ship with the package).
-- Christian
PS: And I registered pyogp.net for having a shortname for my
presentation instead of the wiki link. It redirects there. I hope
that's ok with everybody :)
_______________________________________________
Click here to unsubscribe or manage your list subscription:
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp
--
Christian Scholz Homepage: http://comlounge.net
COM.lounge blog: http://mrtopf.de/blog
Luetticher Strasse 10 Skype: HerrTopf
52064 Aachen Video Blog: http://comlounge.tv
Tel: +49 241 400 730 0 E-Mail [EMAIL PROTECTED]
Fax: +49 241 979 00 850 IRC: MrTopf, Tao_T
neue Show: TOPFtäglich (http://mrtopf.de/blog/category/topf-taglich/)
_______________________________________________
Click here to unsubscribe or manage your list subscription:
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp
