Create a single-page reST->HTML generator #113

Open mosra opened 5 years ago

Suggested by /u/AndydeCleyre on Reddit, besides that I bet I'm far from being the only one who sometimes needs to render a quick'n'dirty reST page into HTML and put it somewhere:

quickly plot benchmark results
render a math equation
explain some code, include links to docs etc
dot graph
a README with fancier rendering than what GitHub/GitLab provides etc.

and right now, there's no easy way to achieve this with m.css -- one has to either install Pelican and set up the whole site, or abuse the Python doc generator (which doesn't need Pelican on its own, but still requires you to have a config file). Ideally it would be as simple as

rst2mcss.py in.rst out.html

picking up a header/footer-less full-page template, bundling the CSS inside that page and producing a self-contained page. Goal of this is providing just a single-page rendering, for multiple pages, crosslinking, tagging, categories, ... please just use Pelican or the Python doc generator. Further possibilities:

ability to switch to a different color theme via a preset (--theme dark, --theme light, or specifying a path to a (self-contained) CSS --theme my-theme.css)
ability to switch to a different layout template via a preset or by supplying the HTML directly (ideas: plain page, TOC on a side, heeader/footer "branding"...)
ability to opt-out of CSS embedding (--external-css?)
because some plugins need additional config, have an ability to supply a config file
- or pick it up implicitly, look for rst2mcss.conf.py next to in.rst?
- an ability to supply config options on command-line? -c "M_HTMLSANITY_HYPHENATION=True;M_HTMLSANITY_SMART_QUOTES=True"?
- or config presets, enabling a particular set of plugins (-c minimal, -c full, ...)?

I decided to try abusing this project to get this done for a README again, and here's what I found:

I started with pelican, but found that it was duplicating the beginning as a sort of summary at the top, and posting the date, and basically I didn't know how to/care to find all the ways to de-blogify it.
I got pretty good results with the python doc generator. The only real things I'm missing from the output are:
- a sticky "local" table of contents (for sections in the file, always accessible at any scroll level)
- code block coloring (maybe it's working, but all the text is the same color)

Some details from my setup:

conf.py:

PROJECT_TITLE = "zpy"
PROJECT_SUBTITLE = "Zsh helpers for Python venvs, with pip-tools"
MAIN_PROJECT_URL = 'https://github.com/andydecleyre/zpy'
OUTPUT = '../../docs'
INPUT_PAGES = ['../../build/index.rst']
LINKS_NAVBAR1 = [
    ("Light", 'https://zpy.rtfd.io', []),
    ("Source", 'https://github.com/andydecleyre/zpy', []),
    ("Issues", 'https://github.com/andydecleyre/zpy/issues', []),
    ("pip-tools", 'https://github.com/jazzband/pip-tools', []),
]
SEARCH_DISABLED = True
FAVICON = '../favicon-32x32.png'

build script:

#!/bin/sh -e
gitroot="$(git -C "$(dirname "$0")" rev-parse --show-toplevel)"

[ $VIRTUAL_ENV ] \
|| printf '%s\n' \
  'You may want to activate a venv first in order to install and use the build tools.' \
  'Trying anyway . . .'
pip install -qr "${gitroot}/doc/m.css/requirements.txt"
git -C "${gitroot}" submodule update --init --recursive

"${gitroot}/mk/doc/readme.sh"
cp "${gitroot}/README.rst" "${gitroot}/build/index.rst"

rm -rf "${gitroot}/docs"
"${gitroot}/doc/m.css/m.css/documentation/python.py" "${gitroot}/doc/m.css/conf.py"

rm \
    "${gitroot}/build/index.rst" \
    "${gitroot}/docs/classes.html" \
    "${gitroot}/docs/modules.html" \
    "${gitroot}/docs/pages.html"

README @ github & raw

The results ~are currently rendered @ https://andydecleyre.github.io/zpy/ and~ should be reliably available at this commit

mosra / m.css

Create a single-page reST->HTML generator #113