Working on help text

With a help viewer in place, it's time to add some help text in the form of an HTML page. Version 1, the help page was all hand-made HTML. Readable and well-organized (because I be an ace tech writer, ya know) but frankly, ugly to look at.

So for V2 I thought I'd use some doc-making package to build a nice themed page. Friday afternoon I took quick looks at several and somewhat reluctantly settled on Sphinx.

The reluctance to use what appears to be a mature, well-supported system comes, mostly, from the fact that Sphinx requires the use of reStructuredText as its input markup. I dislike several things about rST. Its syntax is arbitrary to the point of parody. I got familiar with rST while I was rewriting the doc for PyInstaller. Familiarity did not exactly breed contempt, but it didn't make me like rST either. It's just another text markup language, more complicated but maybe more complete than Markdown. Anyway.

So I started writing the Help doc for version 2. Copying lots of text from the V1 doc of course, but also rewriting for greater simplicity and clarity. I'm using lots of simple declarative sentences. One goal for V2 is to be usable in other languages than English. All the user-visible character strings in the code--buttons, titles, tooltips, errors, etc.--are enclosed in calls to tr(), the Qt translator. If there is a translation file for the current locale, they'll display in the local language.

There's no automatic translation system for a big fat HTML page (or a big fat .rst source file). But at least it will be easy to translate, if anyone ever wants to. And if not translated, easy to read for someone with English as a second or third language.

The HTML generated by Sphinx poses another problem. The V1 help was of course a single self-contained .html file, and that's what I expected to have for V2. But Sphinx does not make self-contained HTML. The HTML page it makes has half a dozen references to files in a folder named _static assumed to be next to the page.

The Sphinx build system has an option singlehtml, but that just guarantees there will be only one HTML file in the output. Normally it expects you to have a set of multiple .rst files, say one per chapter, and it makes an index.html file plus other linked files. The singlehtml build option puts all the HTML files in one, but that one still has references to CSS and javascripts in _static. (And, it doesn't have a table of contents.)

So where in V1 I had a single file, V2 will have a file plus a folder of support files. This annoys me because it's more stuff to be checked-in and put under git control, and more stuff to be distributed in the "extras" folder.

I'm not clear yet on how to organize this. The viewer code looks in the "extras" path for a file ppqt2help.html. Probably there will be a folder named "html" containing index.html and the _static folder it depends on. This is the structure Sphinx builds. Beside it will be a link, ppqt2help.html, which points to html/index.html. So the viewer can open that name and get the right page.

I have been enjoying writing bits of the help text at odd moments of the day, pretty much whenever I have a free ten minutes. Coding is very satisfying, but writing clear, terse prose is even nicer.

Monday, I hope to get back to pyqtdeploy and make some real progress with it.