Lateral Opinion (rst2qhc)

Using assistant from PyQt

Sun, 01 Mar 2009 10:43:00 GMT

The uRSSus doc is slowly growing, so I hooked assistant to the UI. Not difficult, but I have not seen it elsewhere.

Here's how:

Assume the "Handbook action" is called action_Handbook. Set window.assistant to None in __init__.

def on_action_Handbook_triggered(self, i=None):
    if i==None: return

    if not self.assistant or \
       not self.assistant.poll()==None:

        helpcoll=os.path.join(os.path.abspath(os.path.dirname(__file__)),\
                              'help',\
                              'out',\
                              'collection.qhc')
        cmd="assistant -enableRemoteControl -collectionFile %s"%helpcoll
        self.assistant=subprocess.Popen(cmd,
                                        shell=True,
                                        stdin=subprocess.PIPE)
    self.assistant.stdin.write("SetSource qthelp://urssus/doc/handbook.html\n")

And that's it. Now I ned to figure out context help.

rst2qhc 0.2: the insomnia release

Mon, 23 Feb 2009 11:22:00 GMT

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:

Now you, too can create Qt Help Files painlessly

Sun, 22 Feb 2009 03:18:00 GMT

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