* [PATCH v2 1/5] doc: Allow rst2man.py as an alternative to rst2man
2014-05-10 17:03 [PATCH v2 0/5] rst2man.py support and doc-build cleanups W. Trevor King
@ 2014-05-10 17:03 ` W. Trevor King
2014-07-12 8:00 ` Tomi Ollila
2014-05-10 17:03 ` [PATCH v2 2/5] doc/prerst2man.py: Convert execfile to import W. Trevor King
` (3 subsequent siblings)
4 siblings, 1 reply; 8+ messages in thread
From: W. Trevor King @ 2014-05-10 17:03 UTC (permalink / raw)
To: notmuch; +Cc: Tomi Ollila
Gentoo's dev-python/docutils-0.10 installs Docutils scripts with a
*.py extension, so I have /usr/bin/rst2man.py and no rst2man script.
This patch supports users with both types of systems by checking for
rst2man, falling back on rst2man.py, and giving up only if neither is
found. Users can also set the new RST2MAN path variable explicitly
when they call Make:
make RST2MAN=/my/custom/rst_to_man_converter build-man
I use POSIX's 'command -v' [1] to find the path to rst2man or
rst2man.py, and save that as RST2MAN in Makefile.config. Then pass
the configured RST2MAN path through to prerst2man.py to use in its
system call.
We can use a non-empty RST2MAN to check for the availability of an
rst2man program, so there's no need for a separate HAVE_RST2MAN.
However, we keep the existing HAVE_RST2MAN for consistency with
HAVE_SPHINX.
[1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
---
configure | 15 +++++++++++++--
doc/Makefile.local | 2 +-
doc/prerst2man.py | 9 +++++----
3 files changed, 19 insertions(+), 7 deletions(-)
diff --git a/configure b/configure
index 9bde2eb..f017af8 100755
--- a/configure
+++ b/configure
@@ -413,17 +413,24 @@ if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev
printf "Yes.\n"
have_sphinx=1
have_rst2man=0
+ RST2MAN=
else
printf "No (falling back to rst2man).\n"
have_sphinx=0
printf "Checking if rst2man is available... "
if rst2man -V > /dev/null 2>&1; then
- printf "Yes.\n"
have_rst2man=1
+ RST2MAN=$(command -v rst2man)
+ printf "Yes (${RST2MAN}).\n"
+ elif rst2man.py -V > /dev/null 2>&1; then
+ have_rst2man=1
+ RST2MAN=$(command -v rst2man.py)
+ printf "Yes (${RST2MAN}).\n"
else
- printf "No (so will not install man pages).\n"
have_rst2man=0
+ RST2MAN=
+ printf "No (so will not install man pages).\n"
fi
fi
@@ -820,6 +827,10 @@ HAVE_SPHINX=${have_sphinx}
# Whether there's a rst2man binary available for building documentation
HAVE_RST2MAN=${have_rst2man}
+# The path to the rst2man program for building documentation. Set to
+# an empty string if no such program is available.
+RST2MAN=${RST2MAN}
+
# The directory to which desktop files should be installed
desktop_dir = \$(prefix)/share/applications
diff --git a/doc/Makefile.local b/doc/Makefile.local
index bbd4610..d96cdd5 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -49,7 +49,7 @@ ifeq ($(HAVE_SPHINX),1)
mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
done
else ifeq ($(HAVE_RST2MAN),1)
- $(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
+ $(prerst2man) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
else
@echo "Fatal: build dependency fail."
@false
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 437dea9..81ce817 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -4,8 +4,9 @@ from os.path import dirname, isdir
from os import makedirs, system
import re
-sourcedir = argv[1]
-outdir = argv[2]
+rst2man = argv[1]
+sourcedir = argv[2]
+outdir = argv[3]
if not isdir(outdir):
makedirs(outdir, 0o755)
@@ -59,5 +60,5 @@ for page in man_pages:
outfile.write("".join(lines))
outfile.close()
- system('set -x; rst2man {0} {1}/{2}.{3}'
- .format(filename, outdir, page[0], page[4]))
+ system('set -x; {0} {1} {2}/{3}.{4}'
+ .format(rst2man, filename, outdir, page[0], page[4]))
--
1.9.1.353.gc66d89d
^ permalink raw reply related [flat|nested] 8+ messages in thread* Re: [PATCH v2 1/5] doc: Allow rst2man.py as an alternative to rst2man
2014-05-10 17:03 ` [PATCH v2 1/5] doc: Allow rst2man.py as an alternative to rst2man W. Trevor King
@ 2014-07-12 8:00 ` Tomi Ollila
0 siblings, 0 replies; 8+ messages in thread
From: Tomi Ollila @ 2014-07-12 8:00 UTC (permalink / raw)
To: W. Trevor King, notmuch
On Sat, May 10 2014, "W. Trevor King" <wking@tremily.us> wrote:
> Gentoo's dev-python/docutils-0.10 installs Docutils scripts with a
> *.py extension, so I have /usr/bin/rst2man.py and no rst2man script.
> This patch supports users with both types of systems by checking for
> rst2man, falling back on rst2man.py, and giving up only if neither is
> found. Users can also set the new RST2MAN path variable explicitly
> when they call Make:
>
> make RST2MAN=/my/custom/rst_to_man_converter build-man
>
> I use POSIX's 'command -v' [1] to find the path to rst2man or
> rst2man.py, and save that as RST2MAN in Makefile.config. Then pass
> the configured RST2MAN path through to prerst2man.py to use in its
> system call.
The comment block above can be removed if the change I suggest below will
be done...
>
> We can use a non-empty RST2MAN to check for the availability of an
> rst2man program, so there's no need for a separate HAVE_RST2MAN.
> However, we keep the existing HAVE_RST2MAN for consistency with
> HAVE_SPHINX.
>
> [1]: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/command.html
ditto
> ---
> configure | 15 +++++++++++++--
> doc/Makefile.local | 2 +-
> doc/prerst2man.py | 9 +++++----
> 3 files changed, 19 insertions(+), 7 deletions(-)
>
> diff --git a/configure b/configure
> index 9bde2eb..f017af8 100755
> --- a/configure
> +++ b/configure
> @@ -413,17 +413,24 @@ if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev
> printf "Yes.\n"
> have_sphinx=1
> have_rst2man=0
> + RST2MAN=
> else
> printf "No (falling back to rst2man).\n"
> have_sphinx=0
>
> printf "Checking if rst2man is available... "
> if rst2man -V > /dev/null 2>&1; then
> - printf "Yes.\n"
> have_rst2man=1
> + RST2MAN=$(command -v rst2man)
This could be just RST2MAN=rst2man -- for consistency -- otherwise we'd
need to give the same treatment to all other commands we check...
> + printf "Yes (${RST2MAN}).\n"
> + elif rst2man.py -V > /dev/null 2>&1; then
> + have_rst2man=1
> + RST2MAN=$(command -v rst2man.py)
Ditto, RST2MAN=rst2man.py
> + printf "Yes (${RST2MAN}).\n"
> else
> - printf "No (so will not install man pages).\n"
> have_rst2man=0
> + RST2MAN=
> + printf "No (so will not install man pages).\n"
> fi
> fi
Tomi
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH v2 2/5] doc/prerst2man.py: Convert execfile to import
2014-05-10 17:03 [PATCH v2 0/5] rst2man.py support and doc-build cleanups W. Trevor King
2014-05-10 17:03 ` [PATCH v2 1/5] doc: Allow rst2man.py as an alternative to rst2man W. Trevor King
@ 2014-05-10 17:03 ` W. Trevor King
2014-05-10 17:03 ` [PATCH v2 3/5] doc/prerst2x.py: Adjust to handle any output format, not just man pages W. Trevor King
` (2 subsequent siblings)
4 siblings, 0 replies; 8+ messages in thread
From: W. Trevor King @ 2014-05-10 17:03 UTC (permalink / raw)
To: notmuch; +Cc: Tomi Ollila
excefile is gone in Python 3 [1]. Instead of exec-ing the
configuration, it's easier to insert the source directory in Python's
path [2], and just import the configuration. With this change,
prerst2man.py is compatible with both Python 2 and 3.
[1]: https://docs.python.org/3.0/whatsnew/3.0.html#builtins
[2]: https://docs.python.org/3/library/sys.html#sys.path
---
doc/prerst2man.py | 18 ++++++++++--------
1 file changed, 10 insertions(+), 8 deletions(-)
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 81ce817..7d78e9b 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -1,18 +1,20 @@
-from sys import argv
+import sys
from datetime import date
from os.path import dirname, isdir
from os import makedirs, system
import re
-rst2man = argv[1]
-sourcedir = argv[2]
-outdir = argv[3]
+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)
-execfile(sourcedir + "/conf.py")
-
def header(file, startdocname, command, description, authors, section):
file.write("""
@@ -29,10 +31,10 @@ def header(file, startdocname, command, description, authors, section):
'-' * len(description),
description,
'-' * len(description),
-date.today().isoformat(), release, section, project))
+date.today().isoformat(), conf.release, section, conf.project))
blankre = re.compile("^\s*$")
-for page in man_pages:
+for page in conf.man_pages:
outdirname = outdir + '/' + dirname(page[0])
if not isdir(outdirname):
makedirs(outdirname, 0o755)
--
1.9.1.353.gc66d89d
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 3/5] doc/prerst2x.py: Adjust to handle any output format, not just man pages
2014-05-10 17:03 [PATCH v2 0/5] rst2man.py support and doc-build cleanups W. Trevor King
2014-05-10 17:03 ` [PATCH v2 1/5] doc: Allow rst2man.py as an alternative to rst2man W. Trevor King
2014-05-10 17:03 ` [PATCH v2 2/5] doc/prerst2man.py: Convert execfile to import W. Trevor King
@ 2014-05-10 17:03 ` W. Trevor King
2014-07-12 8:16 ` Tomi Ollila
2014-05-10 17:03 ` [PATCH v2 4/5] doc: Consolidate Makefile targets around {build|install}-{format} W. Trevor King
2014-05-10 17:03 ` [PATCH v2 5/5] doc: Add rst2html support for building HTML docs W. Trevor King
4 siblings, 1 reply; 8+ messages in thread
From: W. Trevor King @ 2014-05-10 17:03 UTC (permalink / raw)
To: notmuch; +Cc: Tomi Ollila
For example, with these changes we can build HTML output using:
$ prerst2x.py rst2html ${SRCDIR} ${OUTDIR} html
The extension adjustment ensures that the output filenames from the
above command match what we currently generate with sphinx-html.
---
doc/Makefile.local | 4 +--
doc/prerst2man.py | 66 -----------------------------------------------
doc/prerst2x.py | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 77 insertions(+), 68 deletions(-)
delete mode 100644 doc/prerst2man.py
create mode 100644 doc/prerst2x.py
diff --git a/doc/Makefile.local b/doc/Makefile.local
index d96cdd5..5fb526b 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
+prerst2x := python $(srcdir)/$(dir)/prerst2x.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
+ $(prerst2x) "$(RST2MAN)" $(srcdir)/doc $(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..0000000
--- 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/prerst2x.py b/doc/prerst2x.py
new file mode 100644
index 0000000..4f9213f
--- /dev/null
+++ b/doc/prerst2x.py
@@ -0,0 +1,75 @@
+import sys
+from datetime import date
+from os.path import dirname, isdir
+from os import makedirs, system
+import re
+
+rst2x = sys.argv[1]
+sourcedir = sys.argv[2]
+outdir = sys.argv[3]
+try:
+ extension = sys.argv[4]
+except IndexError:
+ extension = ''
+
+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 rst2x 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()
+
+ if extension:
+ ext = extension
+ else:
+ ext = page[4] # man page section
+
+ system('set -x; {0} {1} {2}/{3}.{4}'
+ .format(rst2x, filename, outdir, page[0], ext))
--
1.9.1.353.gc66d89d
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 4/5] doc: Consolidate Makefile targets around {build|install}-{format}
2014-05-10 17:03 [PATCH v2 0/5] rst2man.py support and doc-build cleanups W. Trevor King
` (2 preceding siblings ...)
2014-05-10 17:03 ` [PATCH v2 3/5] doc/prerst2x.py: Adjust to handle any output format, not just man pages W. Trevor King
@ 2014-05-10 17:03 ` W. Trevor King
2014-05-10 17:03 ` [PATCH v2 5/5] doc: Add rst2html support for building HTML docs W. Trevor King
4 siblings, 0 replies; 8+ messages in thread
From: W. Trevor King @ 2014-05-10 17:03 UTC (permalink / raw)
To: notmuch; +Cc: Tomi Ollila
The rst2man target was removed in 9d9a700 (doc: build man pages at
build time; introduce HAVE_SPHINX, HAVE_RST2MAN, 2014-03-13), but a
reference in the install docs slipped through. While I was removing
that reference, I also:
* Converted doc/INSTALL to reStructuredText, so I can link to Sphinx
and Docutils directly. Not everyone has access to Debian's
python-docutils, so it's better to be genric here.
* Converted from an unordered list to paragraphs, because I think it
flows better.
* Dropped the rst2man no-automatic-install caveat. I don't think this
applies to the current code, although I haven't tried to track down
a commit that adds the automatic-install support. Anyhow,
$ make HAVE_SPHINX=0 HAVE_RST2MAN=1 RST2MAN=rst2man.py DESTDIR=/tmp/ install-man
works for me.
* Restructured the Makefile to use build- and install- prefixes
consistently, regardless of Sphinx/rst2x backend.
* Instead of disabling the build-man and install-man targets if
HAVE_SPHINX and HAVE_RST2MAN are both empty, just pull build-man and
install-man out of the default build tree. That way:
$ make HAVE_SPHINX=0 HAVE_RST2MAN=0 build-man
will fail like it should, instead of successfully doing nothing. If
packagers *do* want to force building the docs, despite any config
settings, you can override the BUILD_MAN and INSTALL_MAN variables:
$ make BUILD_MAN=build-man all
---
Makefile.local | 14 ++++++++++++--
doc/INSTALL | 44 ++++++++++++++++++++++++++++++--------------
doc/Makefile.local | 42 ++++++++++++++++++++++++------------------
3 files changed, 66 insertions(+), 34 deletions(-)
diff --git a/Makefile.local b/Makefile.local
index fa07d81..83984fd 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -43,6 +43,15 @@ GPG_FILE=$(SHA1_FILE).asc
PV_FILE=bindings/python/notmuch/version.py
+# Disable docs if we don't have the builders
+ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
+BUILD_MAN =
+INSTALL_MAN =
+else
+BUILD_MAN = build-man
+INSTALL_MAN = install-man
+endif
+
# Smash together user's values with our extra values
FINAL_CFLAGS = -DNOTMUCH_VERSION=$(VERSION) $(CPPFLAGS) $(CFLAGS) $(WARN_CFLAGS) $(extra_cflags) $(CONFIGURE_CFLAGS)
FINAL_CXXFLAGS = $(CPPFLAGS) $(CXXFLAGS) $(WARN_CXXFLAGS) $(extra_cflags) $(extra_cxxflags) $(CONFIGURE_CXXFLAGS)
@@ -58,7 +67,7 @@ endif
FINAL_LIBNOTMUCH_LDFLAGS = $(LDFLAGS) $(AS_NEEDED_LDFLAGS) $(CONFIGURE_LDFLAGS)
.PHONY: all
-all: notmuch notmuch-shared build-man
+all: notmuch notmuch-shared $(BUILD_MAN)
ifeq ($(MAKECMDGOALS),)
ifeq ($(shell cat .first-build-message 2>/dev/null),)
@NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all
@@ -299,7 +308,8 @@ notmuch-shared: $(notmuch_client_modules) lib/$(LINKER_NAME)
$(call quiet,$(FINAL_NOTMUCH_LINKER) $(CFLAGS)) $(notmuch_client_modules) $(FINAL_NOTMUCH_LDFLAGS) -o $@
.PHONY: install
-install: all install-man
+
+install: all $(INSTALL_MAN)
mkdir -p "$(DESTDIR)$(prefix)/bin/"
install notmuch-shared "$(DESTDIR)$(prefix)/bin/notmuch"
ifeq ($(MAKECMDGOALS), install)
diff --git a/doc/INSTALL b/doc/INSTALL
index e37c2b9..8352f7b 100644
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -1,24 +1,40 @@
+.. -*- rst -*-
+
This file contains some more detailed information about building and
installing the documentation.
-Building with sphinx.
----------------------
+Building with Sphinx
+--------------------
-- You need sphinx at least version 1.0.
+With Sphinx_ version 1.0 or greater, you can build HTML, man, and info
+versions of the documentation with::
-- You can build build and install man pages with 'make install-man'
+ make build-{html|info|man}
-- You can build man, info, html, and pdf versions of the docs
- (currently only the man pages) with
+You can build and install the documentation with::
- 'make install-{man|info|html|pdf}'
+ make install-{info|man}
-Building the man pages
+Building with Docutils
----------------------
-- You can build the man pages with rst2man (from python-docutils) with
- 'make rst2man'.
-
-- Currently there is no support to automagically install the resulting
- nroff files, but it should work to modify the target install-man
- in doc/Makefile.local.
+If you don't have Sphinx installed, you can use Docutils_ with the
+same targets outlined above for Sphinx. The Docutils converters
+(rst2man, rst2html, etc.) are used instead of Sphinx. Only the man
+targets are currently supported.
+
+Configuring the builder
+-----------------------
+
+The builder (Sphinx or rst2man) used for compilation is chosen based
+on variables set in ``Makefile.config`` by the ``configure`` script.
+If ``HAVE_SPHINX`` is 1, ``SPHINXBUILD`` (``sphinx-build`` by default)
+is used to build the documentation. If ``HAVE_SPHINX`` is not 1, and
+``HAVE_RST2MAN`` is 1, ``RST2MAN`` is used to build the documentation.
+The ``configure`` script autodetects ``rst2man`` or ``rst2man.py`` in
+your ``PATH`` and sets an appropriate ``RST2MAN`` in
+``Makefile.config``. If neither ``HAVE_SPHINX`` nor ``HAVE_RST2MAN``
+is 1, attempting to build the documentation will fail with an error.
+
+.. _Sphinx: http://sphinx-doc.org/
+.. _Docutils: http://docutils.sourceforge.net/
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 5fb526b..49aa6dd 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -13,22 +13,35 @@ mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py
# Internal variables.
ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir)
-.PHONY: sphinx-html sphinx-texinfo sphinx-info
+.PHONY: build-html build-info build-texinfo build-man
-.PHONY: install-man build-man
+.PHONY: install-info install-man
%.gz: %
rm -f $@ && gzip --stdout $^ > $@
-sphinx-html:
+build-html:
+ifeq ($(HAVE_SPHINX),1)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
+else
+ @echo "fatal: no Sphinx, cannot build HTML docs"
+ @false
+endif
-sphinx-texinfo:
+build-texinfo:
+ifeq ($(HAVE_SPHINX),1)
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
+else
+ @echo "fatal: no Sphinx or rst2texinfo, cannot build texinfo docs"
+ @false
+endif
-sphinx-info: sphinx-texinfo
+build-info: build-texinfo
make -C $(DOCBUILDDIR)/texinfo info
+install-info: build-info
+ make -C $(DOCBUILDDIR)/texinfo install-info
+
-include $(dir)/docdeps.mk
MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
@@ -51,20 +64,14 @@ ifeq ($(HAVE_SPHINX),1)
else ifeq ($(HAVE_RST2MAN),1)
$(prerst2x) "$(RST2MAN)" $(srcdir)/doc $(DOCBUILDDIR)/man
else
- @echo "Fatal: build dependency fail."
+ @echo "fatal: no Sphinx or rst2man, cannot build man pages"
@false
endif
- touch ${MAN_ROFF_FILES} $@
-
-# Do not try to build or install man pages if a man page converter is
-# not available.
-ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
-build-man:
-install-man:
- @echo "No sphinx or rst2man, will not install man pages."
-else
-build-man: ${MAN_GZIP_FILES}
-install-man: ${MAN_GZIP_FILES}
+ touch "$@"
+
+build-man: $(MAN_ROFF_FILES)
+
+install-man: $(MAN_GZIP_FILES)
mkdir -p "$(DESTDIR)$(mandir)/man1"
mkdir -p "$(DESTDIR)$(mandir)/man5"
mkdir -p "$(DESTDIR)$(mandir)/man7"
@@ -72,7 +79,6 @@ install-man: ${MAN_GZIP_FILES}
install -m0644 $(DOCBUILDDIR)/man/man5/*.5.gz $(DESTDIR)/$(mandir)/man5
install -m0644 $(DOCBUILDDIR)/man/man7/*.7.gz $(DESTDIR)/$(mandir)/man7
cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
-endif
$(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py
$(mkdocdeps) $(srcdir)/doc $(DOCBUILDDIR) $@
--
1.9.1.353.gc66d89d
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v2 5/5] doc: Add rst2html support for building HTML docs
2014-05-10 17:03 [PATCH v2 0/5] rst2man.py support and doc-build cleanups W. Trevor King
` (3 preceding siblings ...)
2014-05-10 17:03 ` [PATCH v2 4/5] doc: Consolidate Makefile targets around {build|install}-{format} W. Trevor King
@ 2014-05-10 17:03 ` W. Trevor King
4 siblings, 0 replies; 8+ messages in thread
From: W. Trevor King @ 2014-05-10 17:03 UTC (permalink / raw)
To: notmuch; +Cc: Tomi Ollila
We already fall back to rst2man if Sphinx isn't available for building
the man pages. With this commit we'll fall back to rst2html for
building the HTML docs too. The only tricky bit here is that
HAVE_SPHINX explicitly checks for sphinx.writers.manpage. I'm just
assuming sphinx.writers.html exists, to avoid adding a separate
SPHINX_HTML variable. However, the HTML builder is Sphinx's default,
so it's hard to imagine it not being installed :p. Perhaps it would
be better to drop the HAVE_* settings and SPHINXBUILD to use:
* SPHINX2MAN empty for not-available, otherwise path to script that
can handle '-b manpage'
* SPHINX2HTML empty for not-available, otherwise path to script that
can handle '-b html'
* RST2MAN empty for not-available, otherwise path to script
* RST2HTML empty for not-available, otherwise path to script
I'm sticking with the less intrusive change for now, but I'm happy
with either approach.
---
configure | 26 +++++++++++++++++++++++++-
doc/INSTALL | 7 +++++--
doc/Makefile.local | 2 ++
3 files changed, 32 insertions(+), 3 deletions(-)
diff --git a/configure b/configure
index f017af8..8fb3d19 100755
--- a/configure
+++ b/configure
@@ -414,8 +414,10 @@ if hash sphinx-build > /dev/null 2>&1 && python -m sphinx.writers.manpage > /dev
have_sphinx=1
have_rst2man=0
RST2MAN=
+ have_rst2html=0
+ RST2HTML=
else
- printf "No (falling back to rst2man).\n"
+ printf "No (falling back to Docutils).\n"
have_sphinx=0
printf "Checking if rst2man is available... "
@@ -432,6 +434,21 @@ else
RST2MAN=
printf "No (so will not install man pages).\n"
fi
+
+ printf "Checking if rst2html is available... "
+ if rst2html -V > /dev/null 2>&1; then
+ have_rst2html=1
+ RST2HTML=$(command -v rst2html)
+ printf "Yes (${RST2HTML}).\n"
+ elif rst2man.py -V > /dev/null 2>&1; then
+ have_rst2html=1
+ RST2HTML=$(command -v rst2html.py)
+ printf "Yes (${RST2HTML}).\n"
+ else
+ have_rst2html=0
+ RST2HTML=
+ printf "No (so can not build HTML docs).\n"
+ fi
fi
libdir_in_ldconfig=0
@@ -831,6 +848,13 @@ HAVE_RST2MAN=${have_rst2man}
# an empty string if no such program is available.
RST2MAN=${RST2MAN}
+# Whether there's a rst2html binary available for building documentation
+HAVE_RST2HTML=${have_rst2html}
+
+# The path to the rst2html program for building documentation. Set to
+# an empty string if no such program is available.
+RST2HTML=${RST2HTML}
+
# The directory to which desktop files should be installed
desktop_dir = \$(prefix)/share/applications
diff --git a/doc/INSTALL b/doc/INSTALL
index 8352f7b..bd00dcf 100644
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -20,8 +20,8 @@ Building with Docutils
If you don't have Sphinx installed, you can use Docutils_ with the
same targets outlined above for Sphinx. The Docutils converters
-(rst2man, rst2html, etc.) are used instead of Sphinx. Only the man
-targets are currently supported.
+(rst2man, rst2html, etc.) are used instead of Sphinx. Only the HTML
+and man targets are currently supported.
Configuring the builder
-----------------------
@@ -36,5 +36,8 @@ your ``PATH`` and sets an appropriate ``RST2MAN`` in
``Makefile.config``. If neither ``HAVE_SPHINX`` nor ``HAVE_RST2MAN``
is 1, attempting to build the documentation will fail with an error.
+A parallel set of variables (``HAVE_RST2HTML`` and ``RST2HTML``) is
+used when building HTML docs with Docutills.
+
.. _Sphinx: http://sphinx-doc.org/
.. _Docutils: http://docutils.sourceforge.net/
diff --git a/doc/Makefile.local b/doc/Makefile.local
index 49aa6dd..d78844a 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -23,6 +23,8 @@ ALLSPHINXOPTS := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(srcdir)/$(dir)
build-html:
ifeq ($(HAVE_SPHINX),1)
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
+else ifeq ($(HAVE_RST2HTML),1)
+ $(prerst2x) "$(RST2HTML)" $(srcdir)/doc $(DOCBUILDDIR)/html html
else
@echo "fatal: no Sphinx, cannot build HTML docs"
@false
--
1.9.1.353.gc66d89d
^ permalink raw reply related [flat|nested] 8+ messages in thread