[PATCH v3 3/5] doc/rst-man2any.py: Adjust to handle any output format, not just man pages
For example, with these changes we can build HTML output using:
$ rst-man2any.py -c rst2html -i ${SRCDIR} -o ${OUTDIR} -e html
The extension adjustment ensures that the output filenames from the
above command match what we currently generate with sphinx-html.
Adding argparse handling at the top of the script tipped this over
into "complicated enough to refactor" for me, so I've shifted the
single-file-conversion logic into a new convert() function and
streamlined things a bit.
---
doc/Makefile.local | 4 +-
doc/prerst2man.py | 66 -
doc/rst-man2any.py | 105 +
3 files changed, 107 insertions(+), 68 deletions(-)
delete mode 100644 doc/prerst2man.py
create mode 100755 doc/rst-man2any.py
diff --git a/doc/Makefile.local b/doc/Makefile.local
index d96cdd5..045f823 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -7,7 +7,7 @@ SPHINXOPTS:= -q
SPHINXBUILD = sphinx-build
DOCBUILDDIR := $(dir)/_build
-prerst2man := python $(srcdir)/$(dir)/prerst2man.py
+rstman2any := python $(srcdir)/$(dir)/rst-man2any.py
mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py
# Internal variables.
@@ -49,7 +49,7 @@ ifeq ($(HAVE_SPHINX),1)
mv $(DOCBUILDDIR)/man/*.$${section}
$(DOCBUILDDIR)/man/man$${section}; \
done
else ifeq ($(HAVE_RST2MAN),1)
- $(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
+ $(rstman2any) --converter "$(RST2MAN)" --input $(srcdir)/doc --output
$(DOCBUILDDIR)/man
else
@echo "Fatal: build dependency fail."
@false
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
deleted file mode 100644
index 7d78e9b..000
--- a/doc/prerst2man.py
+++ /dev/null
@@ -1,66 +0,0 @@
-import sys
-from datetime import date
-from os.path import dirname, isdir
-from os import makedirs, system
-import re
-
-rst2man = sys.argv[1]
-sourcedir = sys.argv[2]
-outdir = sys.argv[3]
-
-sys.path.insert(0, sourcedir)
-import conf
-
-
-if not isdir(outdir):
-makedirs(outdir, 0o755)
-
-
-def header(file, startdocname, command, description, authors, section):
-file.write("""
-{0:s}
-{1:s}
-{2:s}
-
-:Date: {3:s}
-:Version: {4:s}
-:Manual section: {5:d}
-:Manual group: {6:s}
-
-""".format(
-'-' * len(description),
-description,
-'-' * len(description),
-date.today().isoformat(), conf.release, section, conf.project))
-
-blankre = re.compile("^\s*$")
-for page in conf.man_pages:
-outdirname = outdir + '/' + dirname(page[0])
-if not isdir(outdirname):
-makedirs(outdirname, 0o755)
-filename = outdir + '/' + page[0] + '.rst'
-outfile = open(filename, 'w')
-infile = open(sourcedir + '/' + page[0] + '.rst', 'r')
-
-# this is a crude hack. We look for the first blank line, and
-# insert the rst2man header there.
-#
-# XXX consider really parsing input
-
-count = 0
-lines = infile.readlines()
-for line in lines:
-outfile.write(line)
-if (blankre.match(line)):
-break
-count = count + 1
-
-del lines[0:count + 1]
-
-header(outfile, *page)
-
-outfile.write("".join(lines))
-outfile.close()
-
-system('set -x; {0} {1} {2}/{3}.{4}'
- .format(rst2man, filename, outdir, page[0], page[4]))
diff --git a/doc/rst-man2any.py b/doc/rst-man2any.py
new file mode 100755
index 000..52a4f9e
--- /dev/null
+++ b/doc/rst-man2any.py
@@ -0,0 +1,105 @@
+#!/usr/bin/python
+
+import argparse
+import datetime
+import os
+import sys
+
+
+def header(stream, description, authors, section, group, version):
+"Write a man-page's ReST headers to 'stream'."
+if len(authors) != 1:
+raise NotImplementedError(
+'cannot handle {count} authors ({authors}'.format(
+count=len(authors), authors=authors))
+stream.write('\n'.join([
+'{description_rule}',
+'{description}',
+'{description_rule}',
+'',
+':Author: {author}',
+':Date: {date}',
+':Version: {version}',
+':Manual section: {section:d}',
+':Manual group: {group}',
+'',
+'']).format(
+description=description,
+description_rule='-' * len(description),
+author=authors[0],
+date=datetime.date.today().isoformat(),
+version=version,
+section=section,
+group=group))
+
+
+def convert(startdocname, description, authors, section,
+group, version, source_dir, output_dir, command, extension=None):
+"""Convert the ReST source at path to the target format in 'output_dir'.
+
+The initial arguments (startdocname through section) follow
+Sphinx's man_pages option [1].
+
+[1]: http://sphinx-doc.org/config.html#confval-man_pages
+"""
+source_path = os.path.join(source_dir, startdocname) + '.rst'
+output_base = os.path.join(output_dir, startdocname)
+temp_path = output_base + '.rst'
+if
[PATCH v3 3/5] doc/rst-man2any.py: Adjust to handle any output format, not just man pages
For example, with these changes we can build HTML output using:
$ rst-man2any.py -c rst2html -i ${SRCDIR} -o ${OUTDIR} -e html
The extension adjustment ensures that the output filenames from the
above command match what we currently generate with sphinx-html.
Adding argparse handling at the top of the script tipped this over
into complicated enough to refactor for me, so I've shifted the
single-file-conversion logic into a new convert() function and
streamlined things a bit.
---
doc/Makefile.local | 4 +-
doc/prerst2man.py | 66 -
doc/rst-man2any.py | 105 +
3 files changed, 107 insertions(+), 68 deletions(-)
delete mode 100644 doc/prerst2man.py
create mode 100755 doc/rst-man2any.py
diff --git a/doc/Makefile.local b/doc/Makefile.local
index d96cdd5..045f823 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -7,7 +7,7 @@ SPHINXOPTS:= -q
SPHINXBUILD = sphinx-build
DOCBUILDDIR := $(dir)/_build
-prerst2man := python $(srcdir)/$(dir)/prerst2man.py
+rstman2any := python $(srcdir)/$(dir)/rst-man2any.py
mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py
# Internal variables.
@@ -49,7 +49,7 @@ ifeq ($(HAVE_SPHINX),1)
mv $(DOCBUILDDIR)/man/*.$${section}
$(DOCBUILDDIR)/man/man$${section}; \
done
else ifeq ($(HAVE_RST2MAN),1)
- $(prerst2man) $(RST2MAN) $(srcdir)/doc $(DOCBUILDDIR)/man
+ $(rstman2any) --converter $(RST2MAN) --input $(srcdir)/doc --output
$(DOCBUILDDIR)/man
else
@echo Fatal: build dependency fail.
@false
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
deleted file mode 100644
index 7d78e9b..000
--- a/doc/prerst2man.py
+++ /dev/null
@@ -1,66 +0,0 @@
-import sys
-from datetime import date
-from os.path import dirname, isdir
-from os import makedirs, system
-import re
-
-rst2man = sys.argv[1]
-sourcedir = sys.argv[2]
-outdir = sys.argv[3]
-
-sys.path.insert(0, sourcedir)
-import conf
-
-
-if not isdir(outdir):
-makedirs(outdir, 0o755)
-
-
-def header(file, startdocname, command, description, authors, section):
-file.write(
-{0:s}
-{1:s}
-{2:s}
-
-:Date: {3:s}
-:Version: {4:s}
-:Manual section: {5:d}
-:Manual group: {6:s}
-
-.format(
-'-' * len(description),
-description,
-'-' * len(description),
-date.today().isoformat(), conf.release, section, conf.project))
-
-blankre = re.compile(^\s*$)
-for page in conf.man_pages:
-outdirname = outdir + '/' + dirname(page[0])
-if not isdir(outdirname):
-makedirs(outdirname, 0o755)
-filename = outdir + '/' + page[0] + '.rst'
-outfile = open(filename, 'w')
-infile = open(sourcedir + '/' + page[0] + '.rst', 'r')
-
-# this is a crude hack. We look for the first blank line, and
-# insert the rst2man header there.
-#
-# XXX consider really parsing input
-
-count = 0
-lines = infile.readlines()
-for line in lines:
-outfile.write(line)
-if (blankre.match(line)):
-break
-count = count + 1
-
-del lines[0:count + 1]
-
-header(outfile, *page)
-
-outfile.write(.join(lines))
-outfile.close()
-
-system('set -x; {0} {1} {2}/{3}.{4}'
- .format(rst2man, filename, outdir, page[0], page[4]))
diff --git a/doc/rst-man2any.py b/doc/rst-man2any.py
new file mode 100755
index 000..52a4f9e
--- /dev/null
+++ b/doc/rst-man2any.py
@@ -0,0 +1,105 @@
+#!/usr/bin/python
+
+import argparse
+import datetime
+import os
+import sys
+
+
+def header(stream, description, authors, section, group, version):
+Write a man-page's ReST headers to 'stream'.
+if len(authors) != 1:
+raise NotImplementedError(
+'cannot handle {count} authors ({authors}'.format(
+count=len(authors), authors=authors))
+stream.write('\n'.join([
+'{description_rule}',
+'{description}',
+'{description_rule}',
+'',
+':Author: {author}',
+':Date: {date}',
+':Version: {version}',
+':Manual section: {section:d}',
+':Manual group: {group}',
+'',
+'']).format(
+description=description,
+description_rule='-' * len(description),
+author=authors[0],
+date=datetime.date.today().isoformat(),
+version=version,
+section=section,
+group=group))
+
+
+def convert(startdocname, description, authors, section,
+group, version, source_dir, output_dir, command, extension=None):
+Convert the ReST source at path to the target format in 'output_dir'.
+
+The initial arguments (startdocname through section) follow
+Sphinx's man_pages option [1].
+
+[1]: http://sphinx-doc.org/config.html#confval-man_pages
+
+source_path = os.path.join(source_dir, startdocname) + '.rst'
+output_base = os.path.join(output_dir, startdocname)
+temp_path = output_base + '.rst'
+if extension:
+ext =
