krb5 commit: Make rules for building NOTICE from RST

[Benjamin Kaduk]

https://github.com/krb5/krb5/commit/e9dc672b8b3af28fa8ea71e866a7c376b4c443d7
commit e9dc672b8b3af28fa8ea71e866a7c376b4c443d7
Author: Ben Kaduk <kaduk at mit.edu>
Date:   Mon Oct 15 17:47:33 2012 -0400

    Make rules for building NOTICE from RST
    
    Sphinx-build wants to scan over all the sources in the source dir,
    and its text output engine does not handle the spanning row cells
    used in some of our fancy tables, so it will crash if we attempt
    to generate text output from our full suite of documents.
    We could work around this by attempting to just compile the one
    source file as an additional argument to sphinx-build, but this
    seems to insist on producing an index.txt as well as a notice.txt.
    Furthermore, we cannot use the same conf.py as in rst_composite because
    the paths substitutions are not available with just the minimal
    contents of rst_notice.  Make a copy and remove the irrelevant parts,
    for now, changing only the master_doc field as appropriate.
    
    For the HTML build, we use the standard |copy| macro from isonum.txt
    to get the unicode copyright symbol glyph, but for ASCII output we
    prefer to just use the literal "(C)".
    
    ticket: 7407

 doc/rst_source/txt_conf.py |   88 ++++++++++++++++++++++++++++++++++++++++++++
 src/doc/Makefile.in        |   25 ++++++++++--
 2 files changed, 108 insertions(+), 5 deletions(-)

diff --git a/doc/rst_source/txt_conf.py b/doc/rst_source/txt_conf.py
new file mode 100644
index 0000000..f9f00e9
--- /dev/null
+++ b/doc/rst_source/txt_conf.py
@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+#
+# MIT Kerberos documentation build configuration file, created by
+# sphinx-quickstart on Wed Oct 13 09:14:03 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+#extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.doxylink']
+extensions = ['sphinx.ext.autodoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'notice'
+
+# General information about the project.
+project = u'MIT Kerberos'
+copyright = u'2012, MIT'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+today = ' '
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
diff --git a/src/doc/Makefile.in b/src/doc/Makefile.in
index d87a87c..e961f90 100644
--- a/src/doc/Makefile.in
+++ b/src/doc/Makefile.in
@@ -29,10 +29,16 @@ substhtml: composite paths.py
 	cp paths.py rst_composite
 	$(SPHINX_BUILD) -t pathsubs -q rst_composite rst_html_subst
 
+# Create an ASCII (okay, UTF-8) version of the NOTICE file
+notice.txt: rst_notice
+	$(SPHINX_BUILD) -b text -q rst_notice .
+
+NOTICE: notice.txt
+	cp notice.txt $(top_srcdir)/../NOTICE
+
 # Use doxygen to generate API documentation, translate it into RST
-# format, and then create a composite of $(docsrc)/rst_source, the
-# generated files, and the NOTICE file in rst_composite.  Used by the
-# rsthtml and substhtml targets.
+# format, and then create a composite of $(docsrc)/rst_source and the
+# generated files in rst_composite.  Used by the rsthtml and substhtml targets.
 composite: Doxyfile
 	rm -rf doxy rst_apiref rst_composite
 	$(DOXYGEN)
@@ -42,7 +48,15 @@ composite: Doxyfile
 	cp rst_apiref/*.rst rst_composite/krb_appldev/refs/api
 	cp rst_apiref/types/*.rst rst_composite/krb_appldev/refs/types
 	cp rst_apiref/macros/*.rst rst_composite/krb_appldev/refs/macros
-	cp $(top_srcdir)/../NOTICE rst_composite
+
+# Must use a separate source dir for sphinx text builds, since the text
+# engine cannot handle the row spanning cells in fancy tables that we use
+rst_notice: $(docsrc)/notice.rst $(docsrc)/txt_conf.py
+	mkdir -p rst_notice
+	# reST needs backslashes before parens in this macro definition.
+	sed -e 's/include:: <isonum.txt>/|copy| replace:: \\(C\\)/' \
+		< $(docsrc)/rst_source/notice.rst > rst_notice/notice.rst
+	cp $(docsrc)/rst_source/txt_conf.py rst_notice/conf.py
 
 Doxyfile: $(srcdir)/Doxyfile.in
 	sed -e 's|@SRC@|$(top_srcdir)|g' \
@@ -60,4 +74,5 @@ paths.py:
 	echo 'ckeytab = "``$(DEFCKTNAME)``"' >> $@
 
 clean::
-	rm -rf doxy rst_apiref rst_composite rst_html_subst Doxyfile paths.py
+	rm -rf doxy rst_apiref rst_composite rst_notice rst_html_subst \
+		Doxyfile paths.py