Integrate building docs using Sphinx and Doxygen into the makefile

proper. Enabled using --use-sphinx and --use-doxygen options, both of
which default to false. If Sphinx isn't enabled, the ReST sources are
copied directly (a case where having a very readable source format
comes in handy...)

The reference manual (either Sphinx processed into HTML, or the raw
source) and the Doxygen output (if enabled) are copied into the doc
directory upon install on Unix. Currently not done on Windows, the
install target is fairly bogus there currently, and hasn't been tested
in some time.

7 files changed, 98 insertions, 168 deletions

diff --git a/configure.py b/configure.py
index d486e0c71..53651452d 100755
--- a/configure.py
+++ b/configure.py
@@ -69,6 +69,8 @@ class BuildConfigurationInformation(object):
 
         self.use_boost_python = options.boost_python
 
+        self.doc_output_dir = os.path.join(self.build_dir, 'docs')
+
         self.pyobject_dir = os.path.join(self.build_dir, 'python')
 
         self.include_dir = os.path.join(self.build_dir, 'include')
@@ -90,24 +92,39 @@ class BuildConfigurationInformation(object):
              for file in os.listdir(self.python_dir)
              if file.endswith('.cpp')])
 
-    def doc_files(self):
-        return [os.path.join('doc', s)
-                for s in os.listdir('doc') if s.endswith('.txt')] + \
-                ['readme.txt']
+        self.manual_dir = os.path.join(self. doc_output_dir, 'manual')
+
+        def build_doc_commands():
+            yield '$(COPY) readme.txt %s' % (self.doc_output_dir)
+
+            if options.use_sphinx:
+                yield 'sphinx-build -b html doc %s' % (self.manual_dir)
+            else:
+                yield '$(COPY) doc/*.txt %s' % (self.manual_dir)
+
+            if options.use_doxygen:
+                yield 'doxygen %s/botan.doxy' % (self.build_dir)
+
+        self.build_doc_commands = '\n'.join(['\t' + s for s in build_doc_commands()])
+
+        def build_dirs():
+            yield self.checkobj_dir
+            yield self.libobj_dir
+            yield self.botan_include_dir
+            yield self.internal_include_dir
+            yield os.path.join(self.doc_output_dir, 'manual')
+            if options.use_doxygen:
+                yield os.path.join(self.doc_output_dir, 'doxygen')
+
+            if self.use_boost_python:
+                yield self.pyobject_dir
+
+        self.build_dirs = list(build_dirs())
 
     def pkg_config_file(self):
         return 'botan-%d.%d.pc' % (self.version_major,
                                    self.version_minor)
 
-    def build_dirs(self):
-        dirs = [self.checkobj_dir,
-                self.libobj_dir,
-                self.botan_include_dir,
-                self.internal_include_dir]
-        if self.use_boost_python:
-            dirs.append(self.pyobject_dir)
-        return dirs
-
     def username(self):
         return getpass.getuser()
 
@@ -207,6 +224,16 @@ def process_command_line(args):
                            dest='local_config', metavar='FILE',
                            help='include the contents of FILE into build.h')
 
+    build_group.add_option('--distribution-info', metavar='STRING',
+                           help='set distribution specific versioning',
+                           default='unspecified')
+
+    build_group.add_option('--use-sphinx', default=False, action='store_true',
+                           help='Use Sphinx to generate HTML manual')
+
+    build_group.add_option('--use-doxygen', default=False, action='store_true',
+                           help='Use Doxygen to generate HTML API docs')
+
     build_group.add_option('--dumb-gcc', dest='dumb_gcc',
                            action='store_true', default=False,
                            help=SUPPRESS_HELP)
@@ -223,10 +250,6 @@ def process_command_line(args):
                            default=None,
                            help=SUPPRESS_HELP)
 
-    build_group.add_option('--distribution-info', metavar='STRING',
-                           help='set distribution specific versioning',
-                           default='unspecified')
-
     wrapper_group = OptionGroup(parser, 'Wrapper options')
 
     wrapper_group.add_option('--with-boost-python', dest='boost_python',
@@ -965,8 +988,10 @@ def create_template_vars(build_config, options, modules, cc, arch, osinfo):
         'includedir': options.includedir or osinfo.header_dir,
         'docdir': options.docdir or osinfo.doc_dir,
 
-        'doc_src_dir': 'doc',
         'build_dir': build_config.build_dir,
+        'doc_output_dir': build_config.doc_output_dir,
+
+        'build_doc_commands': build_config.build_doc_commands,
 
         'python_dir': build_config.python_dir,
 
@@ -1049,8 +1074,6 @@ def create_template_vars(build_config, options, modules, cc, arch, osinfo):
             os.path.join(build_config.build_dir,
                          build_config.pkg_config_file())),
 
-        'doc_files': makefile_list(build_config.doc_files()),
-
         'mod_list': '\n'.join(sorted([m.basename for m in modules])),
 
         'python_version': options.python_version
@@ -1284,7 +1307,7 @@ def setup_build(build_config, options, template_vars):
         if e.errno != errno.ENOENT:
             logging.error('Problem while removing build dir: %s' % (e))
 
-    for dir in build_config.build_dirs():
+    for dir in build_config.build_dirs:
         try:
             os.makedirs(dir)
         except OSError, e:
diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index e183a36ec..000000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,60 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    = -W
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html singlehtml latex latexpdf text man
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-
-clean:
-	-rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
diff --git a/doc/log.txt b/doc/log.txt
index 1d863c88b..d3bc51004 100644
--- a/doc/log.txt
+++ b/doc/log.txt
@@ -10,7 +10,15 @@ Release Notes
 Version 1.10.0, Not Yet Released
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  * More updates to the documentation
+  * Further updates to the documentation
+
+  * New options to ``configure.py`` control what tools are used for
+    documentation generation. The ``--use-sphinx`` option enables
+    using Sphinx to convert ReST into HTML; otherwise the ReST sources
+    are installed directly. If ``--use-doxygen`` is used, Doxygen will
+    run as well. Documentation generation can be triggered via the
+    ``docs`` target in the makefile; it will also be installed by
+    the install target on Unix.
 
 Version 1.9.16, 2011-04-11
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/src/build-data/botan.doxy.in b/src/build-data/botan.doxy.in
index 2f76a756b..52021c01f 100644
--- a/src/build-data/botan.doxy.in
+++ b/src/build-data/botan.doxy.in
@@ -1,12 +1,9 @@
 # Doxyfile 1.5.4
 
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = Botan
 PROJECT_NUMBER         = %{version}
-OUTPUT_DIRECTORY       = doc/doxygen
+OUTPUT_DIRECTORY       = %{doc_output_dir}/doxygen
+DOXYFILE_ENCODING      = UTF-8
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
@@ -33,6 +30,7 @@ SIP_SUPPORT            = NO
 DISTRIBUTE_GROUP_DOC   = NO
 SUBGROUPING            = YES
 TYPEDEF_HIDES_STRUCT   = NO
+
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------
@@ -63,6 +61,7 @@ MAX_INITIALIZER_LINES  = 30
 SHOW_USED_FILES        = YES
 SHOW_DIRECTORIES       = NO
 FILE_VERSION_FILTER    =
+
 #---------------------------------------------------------------------------
 # configuration options related to warning and progress messages
 #---------------------------------------------------------------------------
@@ -73,6 +72,7 @@ WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = NO
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LOGFILE           =
+
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
@@ -112,7 +112,7 @@ IGNORE_PREFIX          =
 # configuration options related to the HTML output
 #---------------------------------------------------------------------------
 GENERATE_HTML          = YES
-HTML_OUTPUT            = html
+HTML_OUTPUT            = .
 HTML_FILE_EXTENSION    = .html
 HTML_HEADER            =
 HTML_FOOTER            =
@@ -129,56 +129,7 @@ DISABLE_INDEX          = NO
 ENUM_VALUES_PER_LINE   = 4
 GENERATE_TREEVIEW      = NO
 TREEVIEW_WIDTH         = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = a4wide
-EXTRA_PACKAGES         =
-LATEX_HEADER           =
-PDF_HYPERLINKS         = NO
-USE_PDFLATEX           = NO
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    =
-RTF_EXTENSIONS_FILE    =
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN           = NO
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_SCHEMA             =
-XML_DTD                =
-XML_PROGRAMLISTING     = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX =
+
 #---------------------------------------------------------------------------
 # Configuration options related to the preprocessor
 #---------------------------------------------------------------------------
@@ -191,6 +142,7 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             =
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
+
 #---------------------------------------------------------------------------
 # Configuration::additions related to external references
 #---------------------------------------------------------------------------
@@ -199,6 +151,7 @@ GENERATE_TAGFILE       =
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 PERL_PATH              = /usr/bin/perl
+
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
@@ -226,6 +179,7 @@ DOT_TRANSPARENT        = YES
 DOT_MULTI_TARGETS      = NO
 GENERATE_LEGEND        = YES
 DOT_CLEANUP            = YES
+
 #---------------------------------------------------------------------------
 # Configuration::additions related to the search engine
 #---------------------------------------------------------------------------
diff --git a/src/build-data/makefile/nmake.in b/src/build-data/makefile/nmake.in
index 9ca071da3..3e20d988a 100644
--- a/src/build-data/makefile/nmake.in
+++ b/src/build-data/makefile/nmake.in
@@ -17,6 +17,7 @@ DESTDIR       = %{prefix}
 
 ### Aliases for Common Programs
 AR            = %{ar_command}
+COPY          = copy
 CD            = @cd
 ECHO          = @echo
 INSTALL       = %{install_cmd_exec}
@@ -30,8 +31,6 @@ RMDIR         = @rmdir
 ### File Lists
 CHECK         = check
 
-DOCS          = %{doc_files}
-
 HEADERS       = %{include_files}
 
 LIBOBJS       = %{lib_objs}
@@ -67,6 +66,9 @@ $(BOTAN_LIB): $(LIBOBJS)
 !Endif
 
 ### Fake Targets
+docs:
+%{build_doc_commands}
+
 clean:
 	$(RM) %{build_dir}\lib\* %{build_dir}\checks\*
 	$(RM) *.manifest *.exp *.dll
diff --git a/src/build-data/makefile/unix.in b/src/build-data/makefile/unix.in
index ea51c999e..1a1128f81 100644
--- a/src/build-data/makefile/unix.in
+++ b/src/build-data/makefile/unix.in
@@ -24,6 +24,8 @@ PKGCONFIG     = %{botan_pkgconfig}
 
 # Aliases for Common Programs
 AR               = %{ar_command}
+COPY             = cp
+COPY_R           = cp -r
 CD               = @cd
 ECHO             = @echo
 INSTALL_CMD_EXEC = %{install_cmd_exec}
@@ -38,8 +40,6 @@ RM_R             = @rm -rf
 # File Lists
 CHECK         = %{check_prefix}check
 
-DOCS          = %{doc_files}
-
 HEADERS       = %{include_files}
 
 LIBOBJS       = %{lib_objs}
@@ -71,12 +71,12 @@ $(STATIC_LIB): $(LIBOBJS)
 	$(RANLIB) $(STATIC_LIB)
 
 # Fake Targets
-.PHONY = doxygen clean distclean install static
+.PHONY = docs clean distclean install static
 
 static: $(STATIC_LIB)
 
-doxygen:
-	doxygen %{build_dir}/botan.doxy
+docs:
+%{build_doc_commands}
 
 clean:
 	$(RM_R) %{build_dir}/lib/* %{build_dir}/checks/*
@@ -84,22 +84,23 @@ clean:
 
 distclean: clean
 	$(RM_R) %{build_dir}
-	$(RM_R) %{doc_src_dir}/doxygen %{doc_src_dir}/botan.doxy
 	$(RM) Makefile* $(CONFIG_SCRIPT) $(PKGCONFIG)
 
-install: $(LIBRARIES)
+install: $(LIBRARIES) docs
 	$(ECHO) "Installing Botan into $(DESTDIR)... "
 	$(MKDIR_INSTALL) $(DOCDIR)
+	$(COPY_R) %{doc_output_dir}/* $(DOCDIR)
+
 	$(MKDIR_INSTALL) $(HEADERDIR)
-	$(MKDIR_INSTALL) $(LIBDIR)
-	$(MKDIR_INSTALL) $(BINDIR)
-	$(MKDIR_INSTALL) $(PKGCONF_DIR)
-	for i in $(DOCS); do \
-	   $(INSTALL_CMD_DATA) $$i $(DOCDIR); \
-	 done
 	for i in $(HEADERS); do \
 	   $(INSTALL_CMD_DATA) $$i $(HEADERDIR); \
 	 done
+
+	$(MKDIR_INSTALL) $(LIBDIR)
 	$(INSTALL_CMD_DATA) $(STATIC_LIB) $(LIBDIR)
+
+	$(MKDIR_INSTALL) $(BINDIR)
 	$(INSTALL_CMD_EXEC) $(CONFIG_SCRIPT) $(BINDIR)
+
+	$(MKDIR_INSTALL) $(PKGCONF_DIR)
 	$(INSTALL_CMD_DATA) $(PKGCONFIG) $(PKGCONF_DIR)
diff --git a/src/build-data/makefile/unix_shr.in b/src/build-data/makefile/unix_shr.in
index 06a7c3354..c311d9924 100644
--- a/src/build-data/makefile/unix_shr.in
+++ b/src/build-data/makefile/unix_shr.in
@@ -26,6 +26,8 @@ PKGCONFIG     = %{botan_pkgconfig}
 
 # Aliases for Common Programs
 AR               = %{ar_command}
+COPY             = cp
+COPY_R           = cp -r
 CD               = @cd
 ECHO             = @echo
 INSTALL_CMD_EXEC = %{install_cmd_exec}
@@ -40,8 +42,6 @@ RM_R             = @rm -rf
 # File Lists
 CHECK         = %{check_prefix}check
 
-DOCS          = %{doc_files}
-
 HEADERS       = %{include_files}
 
 LIBOBJS       = %{lib_objs}
@@ -83,14 +83,14 @@ $(SHARED_LIB): $(LIBOBJS)
 	$(LN) $(SHARED_LIB) $(SYMLINK)
 
 # Fake Targets
-.PHONY = doxygen clean distclean install static shared
+.PHONY = docs clean distclean install static shared
 
 static: $(STATIC_LIB)
 
 shared: $(SHARED_LIB)
 
-doxygen:
-	doxygen %{build_dir}/botan.doxy
+docs:
+%{build_doc_commands}
 
 clean:
 	$(RM_R) %{build_dir}/lib/* %{build_dir}/checks/*
@@ -98,24 +98,26 @@ clean:
 
 distclean: clean
 	$(RM_R) %{build_dir}
-	$(RM_R) %{doc_src_dir}/doxygen %{doc_src_dir}/botan.doxy
 	$(RM) Makefile* $(CONFIG_SCRIPT) $(PKGCONFIG)
 
-install: $(LIBRARIES)
+install: $(LIBRARIES) docs
 	$(ECHO) "Installing Botan into $(DESTDIR)... "
 	$(MKDIR_INSTALL) $(DOCDIR)
+	$(COPY_R) %{doc_output_dir}/* $(DOCDIR)
+
 	$(MKDIR_INSTALL) $(HEADERDIR)
-	$(MKDIR_INSTALL) $(LIBDIR)
-	$(MKDIR_INSTALL) $(BINDIR)
-	$(MKDIR_INSTALL) $(PKGCONF_DIR)
-	for i in $(DOCS); do \
-	   $(INSTALL_CMD_DATA) $$i $(DOCDIR); \
-	 done
 	for i in $(HEADERS); do \
 	   $(INSTALL_CMD_DATA) $$i $(HEADERDIR); \
 	 done
+
+	$(MKDIR_INSTALL) $(LIBDIR)
 	$(INSTALL_CMD_DATA) $(STATIC_LIB) $(LIBDIR)
-	$(INSTALL_CMD_EXEC) $(CONFIG_SCRIPT) $(BINDIR)
 	$(INSTALL_CMD_EXEC) $(SHARED_LIB) $(LIBDIR)
-	$(INSTALL_CMD_DATA) $(PKGCONFIG) $(PKGCONF_DIR)
 	$(CD) $(LIBDIR); $(LN) $(SHARED_LIB) $(SYMLINK)
+	$(CD) $(LIBDIR); $(LN) $(SHARED_LIB) $(SONAME)
+
+	$(MKDIR_INSTALL) $(BINDIR)
+	$(INSTALL_CMD_EXEC) $(CONFIG_SCRIPT) $(BINDIR)
+
+	$(MKDIR_INSTALL) $(PKGCONF_DIR)
+	$(INSTALL_CMD_DATA) $(PKGCONFIG) $(PKGCONF_DIR)