From: Tomi Ollila <tomi.ollila@iki.fi>
To: David Bremner <david@tethera.net>, notmuch@notmuchmail.org
Subject: Re: [RFC Patch v3 2/3] doc: add target rst2man to build man pages using rst2man
Date: Sun, 23 Feb 2014 19:42:21 +0200 [thread overview]
Message-ID: <m24n3pu3nm.fsf@guru.guru-group.fi> (raw)
In-Reply-To: <1393114575-8756-3-git-send-email-david@tethera.net>
On Sun, Feb 23 2014, David Bremner <david@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
next prev parent reply other threads:[~2014-02-23 17:42 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-01-18 16:00 [RFC Patch] start of sphinx based docs David Bremner
2014-01-19 13:48 ` Tomi Ollila
2014-01-19 18:57 ` David Bremner
2014-01-28 16:12 ` David Bremner
2014-01-28 16:12 ` [RFC Patch v2 1/2] doc: start of sphinx based docs David Bremner
2014-01-28 16:12 ` [RFC Patch v2 2/2] doc: add target rst2man to build man pages using rst2man David Bremner
2014-01-28 22:54 ` Mark Walters
2014-01-29 2:26 ` Re: David Bremner
2014-02-23 0:16 ` v3 of sphinx docs David Bremner
2014-02-23 0:16 ` [RFC Patch v3 1/3] doc: start of sphinx based docs David Bremner
2014-02-23 0:16 ` [RFC Patch v3 2/3] doc: add target rst2man to build man pages using rst2man David Bremner
2014-02-23 17:42 ` Tomi Ollila [this message]
2014-02-23 23:57 ` David Bremner
2014-02-23 0:16 ` [RFC Patch v3 3/3] doc: fix for conversion errors David Bremner
2014-02-24 0:54 ` v3 of sphinx docs Mark Walters
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://notmuchmail.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m24n3pu3nm.fsf@guru.guru-group.fi \
--to=tomi.ollila@iki.fi \
--cc=david@tethera.net \
--cc=notmuch@notmuchmail.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://yhetil.org/notmuch.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).