I am finally publishing my LatinoWare 2008 tutorial, in revised and expanded form. It will probably be a 10-part series, and here is session 1
Why? It's basically undocumented, it looks ugly and it doesn't support template inheritance, which in this case is very useful, because I am actually doing two very similar planets: 1 2.
So, since I saw a plugin to use Vellum templates, which means the templating is pluggable, why not use my favourite templating library (Mako) instead?
It turns out to be very easy to do!
# -*- coding: utf-8 -*- import rawdoglib.plugins from mako.template import Template from mako.lookup import TemplateLookup from mako import exceptions class MakoPlugin: def __init__(self): self.lookup = TemplateLookup(directories=['.'],\ output_encoding='utf-8',\ encoding_errors='replace') def fill_template(self,template, bits, result): self.lookup.put_string('actual',template) t=self.lookup.get_template('actual') try: r=t.render_unicode(**bits) except: r=exceptions.html_error_template().render() result.value=r return False p = MakoPlugin() rawdoglib.plugins.attach_hook("fill_template",\ p.fill_template)
Yup, 20 lines of code!
Today I woke up at 6AM. I had nothing to do until 9, but I woke up and couldn't sleep again.
So, what can I do? I hacked rst2qhc a bit more :-D
Since this is a small project, it is quickly approaching feature complete status (there is really only so much this thing can do).
So, what's new?
Passing options to rst2html, so you can do things like set stylesheets.
Support for a manifest file, so you can list what files should be embedded in the helpfile.
Fixed project support. Now you can optionally ask rst2qhc to create a qhcp file that will build your document.
Better, more complete example that displays most features.
I have only one thing left in my TODO, which is calling the HTML writer via API instead of via system() because that way there is no need to define the keyword role in the document, and I can add syntax highlighting via pygments.
Since I now do have work to do, I will just release 0.2 now ;-)
You can get it from the usual place: http://rst2qhc.googlecode.com
And here's a sample of the input/output:
I decided to add a manual for uRSSus. Since it's a Qt app, I checked how to do one of those neat help files, like the ones that come with Qt apps.
It turns out it's not so simple to create one of those.
You need to create your help in one or more HTML files, then create a XML file that describes what each file is, references for each section, and references for each keyword you want in the index.
For any real-life-size document, that's going to be incredibly annoying.
So, I took my usual escape route when I don't want to do grunt work on docs: Docutils.
Specifically, I wrote rst2qhc which takes one (or more) restructured text files, and creates a nice and clean Qt Help Project file from them, including section titles, references and keywords, which you mark on the text using the 'keyword' role.
What does this mean? Let me be graphical:
The one on the right is nice to read. The one on the left is nice to write. The arrow in the middle is rst2qhc :-)
And here's how the generated qhp file looks for a trivial outline of a manual (and the reason why I don't want to do this manually ;-):
<?xml version="1.0" encoding="UTF-8"?> <QtHelpProject version="1.0"> <namespace>urssus</namespace> <virtualFolder>doc</virtualFolder> <customFilter name="Unknown"> <filterAttribute></filterAttribute> </customFilter> <filterSection> <filterAttribute></filterAttribute> <toc> <section title="The uRSSus Handbook" ref="manual.html"> <section title="Introduction" ref="manual.html#introduction"/> <section title="Quick Start" ref="manual.html#quick-start"/> <section title="Configuration" ref="manual.html#configuration"/> <section title="Credits and License" ref="manual.html#credits-and-license"/> </section> </toc> <keywords> <keyword name="what can you" ref="manual.html#what-can-you-do-using-urssus"/> <keyword name="quick" ref="manual.html#quick-start"/> <keyword name="main window" ref="manual.html#the-main-window"/> </keywords> <files> <file>manual.html</file> </files> </filterSection> </QtHelpProject>
Also, as a bonus, you can create PDF, LaTeX, HTML and ODT files from the same source (heck, you can create freaking man pages).