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

diff --git a/doc/rst_source/txt_conf.py b/doc/rst_source/txt_conf.py
new file mode 100644 (file)
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 d87a87c9654fc714e06db30ddbcbecacc96c2c1b..e961f902a07fb0bb0fc9d3e089898e809a95572b 100644 (file)
--- 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