India PyCon 2009
Quick wallpaper changer
Load testing with Grinder
Adding namespace to XML
Opera RSS to OPML
« PyBlagg is now Spycyroll
» Planning thoughts
reStructuredText: A light, powerful document markup. reST is very nice. I'm finally beginning to enjoy writing documentation.
Ollie Rutherfurd has a very good writeup about using reST, ht2html and python to make and manage a whole web site.
David has also written about YAML improves on XML. As far as I’m concerned, real benefit of YAML and reST is that you don’t have tags using < and > cluttering the content. Because of this, it is a lot easier to type in content. No circus holding down the shift-key again and again.
Repeating myself: ALL tag based languages suck, when you have to type it in.
I'm impressed... I would have enjoyed using that when I did documentation for the jabber project. Since we used DocBook extensively, I became quite familiar with the numerous tags. Man, I type those things a lot.
Thanks for the pointer.
I enjoy using reST too when doing some documentation at work. There are some drawbacks to reST, especially when it's not forgiving with the errors on your text documents. I'm not sure how to integrate the utils to pyblosxom as I was thinking of doing a preformatter with reST. It's actually too slow compared to wiki, so I leave it to just documentation :)
I agree with Wari on both his points. reST is *unforgiving*. The generator (I've tried only HTML) is much slower than the equivalent in Zope STX.
Just how slow are we talking about, here?
ReST is quite deliberately *precise*. I wouldn't say it's any less "forgiving" than StructuredText or Wiki. What it does do is give you a clean error message when you screw up, whereas with ST or Wiki you have to visually check the results and guess what went worng.
Yeah, it's slow. It's far too early in the development of docutils to be talking about speed as a significant issue.
I agreee with the "forgiving" message from Garth.
Oh, another note: I used ReST to produce the gadfly and Roundup documentation. Beautiful. I even have PDFs generated for Roundup. It's a bit of effort at the moment, but the results are quite nice.
Ah, I see Garth's point. Yes, it gives errors - I guess explicit is better than implicit.
Speed is just an observation, but in real life it is not a big deal since I'm not generating documentation real-time. It can take its own sweet time.
I'm not saying that reST is bad, it's very good for documentation, I wish my colleagues used it in place of Word. I used it for most of my documentation.
Being unforgiving just means that people can get frustrated by it, poison for some.
I use reST to generate HTML, PDF and PostScript. I do wish the PDF and ps output is better, but what ever it is, it's better than nothing.
PDF and tex (ps) output, shows the table of contents nicely, it's even a hyperlink in PDF, unfortunately the TOC does not show page numbers.
I don't mind slow for documentation, as mentioned by Babu, but it's definitely something you'd use realtime.
I think an important point to make is that ReST will _generally_ fail gracefully when presented with ambiguous input. It'll insert a warning into the document tree output so it's obvious (hopefully :) what's going on.
Sorry, hit POST to soon then. I meant to continue to say that if it _doesn't_ fail gracefully (ie. it crashes ;) then hey, it's young software and is bound to have edge cases that David didn't forsee ;)