Add HTML version of the manual

[akrabat]

We need a page on the site that has the manual as per http://rst2pdf.ralsina.me/handbook.html.

I thought we could just run manual.rst through rst2html5.py, but that's not quite so easy as manual.rst uses rst2pdf specific directives and options.

We need a single source for the manual, so maybe we need to use Sphinx?

[lornajane]

Or could we convert from PDF? Once the document is created, what happens if we pandoc it? (this might be an awful question, I'm not sure what the quality of the output is like). Or which rst2pdf things does it use? Maybe we can manage without or add some build step to make that easier.

[ralsina]

I have no idea how I generated that page, if it's any consolation :-)

[lornajane]

I count 11 errors when I apply rst2html to the manual.rst file that we have. This doesn't seem too insurmountable, but I'm not sure how to work around some of them in a way that's useful in the HTML output. Also the HTML output isn't very pretty! The issues I see (reading off the output):

• The oddeven directive fails. That's fine, we could possibly just add a pre-build script to remove it as it doesn't mean anything for HTML format
• Some code samples aren't working well, including highlighting lines, including code, or adding line numbers. I'm kind of surprised that rst2html lags behind rst2pdf on this, are we missing a more updated tool here? Or we need to go around patching DocUtils as well? (@ralsina are you hiding some hacked version of rst2html somewhere??)
• The counters and math role are also broken - I assume unsupported in rst2html. I'm not sure how to handle that for HTML though, I'd be happy to add a little pre-processing to fix what we can't render, and add notes into the manual at the appropriate places pointing out that since it's a PDF tool, some stuff really only renders in PDF.

[lornajane]

Ah, I'm pretty sure it's a Nikola build https://getnikola.com/

[ralsina]

Actually, you can hack a rst2html with the rst2pdf code directive, so yes, I have been hiding that in the sense that I never shared it with anyone :-)

Posting it here in a bit

[ralsina]

Not tested in the past few years:

#!/usr/bin/python

# $Id: rst2html.py 4564 2006-05-21 20:44:42Z wiemann $
# Author: David Goodger <goodger@python.org>
# Copyright: This module has been placed in the public domain.

"""
A minimal front end to the Docutils Publisher, producing HTML.
"""

try:
    import locale
    locale.setlocale(locale.LC_ALL, '')
except:
    pass

from docutils.core import publish_cmdline, default_description
from docutils.parsers.rst import directives
import rst2pdf.pygments_code_block_directive
directives.register_directive('code-block', rst2pdf.pygments_code_block_directive.code_block_directive)

description = ('Generates (X)HTML documents from standalone reStructuredText '
               'sources.  ' + default_description)

publish_cmdline(writer_name='html', description=description)

The main reason for this is that the code support in rst2pdf predates that of docutils, and even now, a bunch of years later, it does some things docutils' doesn't do.

It may be reasonable to deprecate it and switch to docutils' even if it means sunsetting a few features.

[ralsina]

As for math, there is now support in docutils (again, rst2pdf supported it earlier) but I don't know how similar it is.

[lornajane]

Ahhh, OK this helped, thanks :)

I've put the donated script into a branch on the main repo (since that's where the manual is) https://github.com/lornajane/rst2pdf/tree/experimental-html-manual and added something to ignore the oddeven directive so now I "just" have broken counter role and math replacement thing. I'll dig around a bit more on those things and also think about some styling - it is pretty ugly just now.

[lornajane]

In case anyone is still following along, there's a WIP pull request here https://github.com/rst2pdf/rst2pdf/pull/697