Add HTML version of the manual
akrabat opened this issue · comments
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?
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.
I have no idea how I generated that page, if it's any consolation :-)
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 behindrst2pdf
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.
Ah, I'm pretty sure it's a Nikola build https://getnikola.com/
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
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.
As for math, there is now support in docutils (again, rst2pdf supported it earlier) but I don't know how similar it is.
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.
In case anyone is still following along, there's a WIP pull request here rst2pdf/rst2pdf#697