[RFC Patch v3 2/3] doc: add target rst2man to build man pages using rst2man
Tomi Ollila
tomi.ollila at iki.fi
Sun Feb 23 09:42:21 PST 2014
On Sun, Feb 23 2014, David Bremner <david at tethera.net> wrote:
> Many people have docutils installed, but not sphinx. Allow these
> people to build the man pages.
+1 from me to start having manuals in reStructuredText format and
then converting these to the target formats. Some comments on
the patch series below:
Building any docs using this is not yet activated ?
Anyway, I tried to build manual pages using 'make man' and got this:
$ make man
sphinx-build -b man -d doc/_build/doctrees -q -c doc doc doc/_build/man
Making output directory...
Sphinx error:
Builder name man not registered
No fallback to use rst2man...
Comments regarding prerst2man.py inline below:
Tomi
> ---
// stuff deleted //
> diff --git a/doc/rst2man/prerst2man.py b/doc/rst2man/prerst2man.py
> new file mode 100644
> index 0000000..797dd20
> --- /dev/null
> +++ b/doc/rst2man/prerst2man.py
> @@ -0,0 +1,53 @@
> +from sys import argv
> +from datetime import date
> +import re
> +
> +sourcedir=argv[1]
> +outdir=argv[2]
Style! run pep8 prerst2html.py and fix the issues it prints
to the screen, like ' = ' above and remove trailing semicolon
below... (and also pep8(1) doc/conf.py.
> +
> +execfile(sourcedir+"/conf.py");
> +
> +
> +
> +
> +def header(file,startdocname, command, description, authors, section):
> + file.write("""
> +{:s}
> +{:s}
> +{:s}
> +
> +:Date: {:s}
> +:Version: {:s}
> +:Manual section: {:d}
> +:Manual group: {:s}
For python < 2.7 these needs to be {0:s}, {1:s}, {2:s}.. {5:d}...
> +
> +""".format(
> +'-' * len(description),
> +description,
> +'-' * len(description),
> +date.today().isoformat(),release,section,project))
Replace date.today.isoformat() with date determined from other
sources (NEWS file?)
> +
> +blankre = re.compile("^\s*$")
> +for page in man_pages:
> + outfile = open(outdir+"/"+page[0]+'.rst','w')
> + infile = open(sourcedir+"/"+page[0]+".rst",'r')
In addition to formatting above, use either ".rst" or '.rst'
(and perhaps other quotations in these 2 lines) for consistency.
> +
> +
> + # 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]
pep8 will in the lime above (as it is not lines[0:count + 1])
I might not have complained but... :D
> +
> + header(outfile,*page)
> +
> + outfile.write("".join(lines))
> --
> 1.8.5.3
More information about the notmuch
mailing list