You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/scripts/gendoc.py

149 lines
5.0 KiB
Python

#! /usr/bin/env python
from docutils.core import publish_file
import fileinput
import glob
import os
import re
import shutil
import subprocess
import sys
os.chdir(os.path.dirname(os.path.abspath(__file__)))
stylesheets = {
"stylesheet_path": ["basic.css", "nature.css", "codehighlight.css"]
}
title_style_matchers = {
"=": re.compile("^=+$"),
"-": re.compile("^-+$")
}
TOP_LEVEL = "="
SECOND_LEVEL = "-"
FILE_FORMAT_MATCHER = re.compile("^[0-9]+_[0-9]{2}[a-z]*_.*\.rst$")
def check_valid_section(filename, section):
if not re.match(FILE_FORMAT_MATCHER, filename):
raise Exception(
"The filename of " + filename + " does not match the expected format " +
"of '##_##_words-go-here.rst'"
)
# we need TWO new lines else the next file's title gets merged
# the last paragraph *WITHOUT RST PRODUCING A WARNING*
if not section[-2:] == "\n\n":
raise Exception(
"The file " + filename + " does not end with 2 new lines."
)
# Enforce some rules to reduce the risk of having mismatched title
# styles.
title_line = section.split("\n")[1]
if title_line != (len(title_line) * title_line[0]):
raise Exception(
"The file " + filename + " doesn't have a title style line on line 2"
)
# anything marked as xx_00_ is the start of a new top-level section
if re.match("^[0-9]+_00_", filename):
if not title_style_matchers[TOP_LEVEL].match(title_line):
raise Exception(
"The file " + filename + " is a top-level section because it matches " +
"the filename format ##_00_something.rst but has the wrong title " +
"style: expected '" + TOP_LEVEL + "' but got '" +
title_line[0] + "'"
)
# anything marked as xx_xx_ is the start of a sub-section
elif re.match("^[0-9]+_[0-9]{2}_", filename):
if not title_style_matchers[SECOND_LEVEL].match(title_line):
raise Exception(
"The file " + filename + " is a 2nd-level section because it matches " +
"the filename format ##_##_something.rst but has the wrong title " +
"style: expected '" + SECOND_LEVEL + "' but got '" +
title_line[0] + "' - If this is meant to be a 3rd/4th/5th-level section " +
"then use the form '##_##b_something.rst' which will not apply this " +
"check."
)
def cat_spec_sections_to(out_file_name):
with open(out_file_name, "wb") as outfile:
for f in sorted(glob.glob("../specification/*.rst")):
with open(f, "rb") as infile:
section = infile.read()
check_valid_section(os.path.basename(f), section)
outfile.write(section)
def rst2html(i, o):
with open(i, "r") as in_file:
with open(o, "w") as out_file:
publish_file(
source=in_file,
destination=out_file,
reader_name="standalone",
parser_name="restructuredtext",
writer_name="html",
settings_overrides=stylesheets
)
def run_through_template(input):
tmpfile = './tmp/output'
try:
with open(tmpfile, 'w') as out:
subprocess.check_output(
[
'python', 'build.py',
"-i", "matrix_templates",
"-o", "../scripts/tmp",
"../scripts/"+input
],
stderr=out,
cwd="../templating",
)
except subprocess.CalledProcessError as e:
with open(tmpfile, 'r') as f:
sys.stderr.write(f.read() + "\n")
raise
def prepare_env():
try:
os.makedirs("./gen")
except OSError:
pass
try:
os.makedirs("./tmp")
except OSError:
pass
def cleanup_env():
shutil.rmtree("./tmp")
def main():
prepare_env()
cat_spec_sections_to("tmp/full_spec.rst")
run_through_template("tmp/full_spec.rst")
shutil.copy("../supporting-docs/howtos/client-server.rst", "tmp/howto.rst")
run_through_template("tmp/howto.rst")
rst2html("tmp/full_spec.rst", "gen/specification.html")
rst2html("tmp/howto.rst", "gen/howtos.html")
if "--nodelete" not in sys.argv:
cleanup_env()
if __name__ == '__main__':
if len(sys.argv) > 1 and sys.argv[1:] != ["--nodelete"]:
# we accept almost no args, so they don't know what they're doing!
print "gendoc.py - Generate the Matrix specification as HTML."
print "Usage:"
print " python gendoc.py [--nodelete]"
print ""
print "The specification can then be found in the gen/ folder."
print ("If --nodelete was specified, intermediate files will be "
"present in the tmp/ folder.")
print ""
print "Requirements:"
print " - This script requires Jinja2 and rst2html (docutils)."
sys.exit(0)
main()