improved build scripts, renamed kea-guide.rst to index.rst

configure.ac

@@ -1440,25 +1440,56 @@ AC_ARG_ENABLE(generate_docs, [AC_HELP_STRING([--enable-generate-docs],
 
 if test "x$enable_generate_docs" != xno ; then
 
-# Check for xsltproc
-  AC_PATH_PROG([SPHINX], [sphinx-build])
-  if test -z "$SPHINX"; then
+# Check for sphinx-build
+  AC_PATH_PROG([SPHINXBUILD], [sphinx-build])
+  if test -z "$SPHINXBUILD"; then
     AC_MSG_ERROR([sphinx-build not found; it is required for --enable-generate-docs, please see http://www.sphinx-doc.org/en/master/usage/installation.html for details])
   else
-    AC_MSG_CHECKING([whether $SPHINX works])
+    AC_MSG_CHECKING([whether $SPHINXBUILD works])
     # run sphinx to see if it works
     # We should probably do a more thorough checks
-    $SPHINX --version
+    $SPHINXBUILD --version
     if test $? -ne 0 ; then
-      AC_MSG_ERROR("Error with $SPHINX --version")
+      AC_MSG_ERROR("Error with $SPHINXBUILD --version")
     fi
-    AC_MSG_RESULT(yes (found in $SPHINX))
+    AC_MSG_RESULT(yes (found in $SPHINXBUILD))
+  fi
+
+# xsltproc --nonet parameter
+  NONET="--nonet"
+  AC_ARG_VAR(XSLTPROC_NET, [xsltproc uses the Internet to fetch DTDs, entities or documents.])
+  if test "x$XSLTPROC_NET" != x ; then
+    NONET=
+  fi
+  AC_SUBST(NONET)
+
+# Check for xsltproc
+  AC_PATH_PROG([XSLTPROC], [xsltproc])
+  if test -z "$XSLTPROC"; then
+    AC_MSG_ERROR("xsltproc not found; it is required for --enable-generate-docs")
+  else
+    AC_MSG_CHECKING([if $XSLTPROC works])
+    # run xsltproc to see if works
+    $XSLTPROC --novalid --xinclude $NONET http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+    if test $? -ne 0 ; then
+      AC_MSG_ERROR("Error with $XSLTPROC using release/xsl/current/manpages/docbook.xsl")
+    fi
+    $XSLTPROC --novalid --xinclude $NONET http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
+    if test $? -ne 0 ; then
+      AC_MSG_ERROR("Error with $XSLTPROC using release/xsl/current/html/docbook.xsl")
+    fi
+    AC_MSG_RESULT(yes)
+  fi
+
+  AC_PATH_PROG([ELINKS], [elinks])
+  if test -z "$ELINKS"; then
+    AC_MSG_ERROR("elinks not found; it is required for --enable-generate-docs")
   fi
 fi
 
 # Don't fail here if not found, used to generate PDF documentation.
-#AC_PATH_PROG([DBLATEX], [dblatex])
-#AM_CONDITIONAL(HAVE_DBLATEX, test "x$DBLATEX" != "x")
+AC_PATH_PROG([DBLATEX], [dblatex])
+AM_CONDITIONAL(HAVE_DBLATEX, test "x$DBLATEX" != "x")
 
 AM_CONDITIONAL(GENERATE_DOCS, test x$enable_generate_docs != xno)
 

doc/Makefile.am

@@ -182,15 +182,6 @@ devel:
 	(cat Doxyfile; echo PROJECT_NUMBER=$(PACKAGE_VERSION)) | doxygen - > html/doxygen.log 2> html/doxygen-error.log
 	echo `grep -i ": warning:" html/doxygen-error.log | wc -l` warnings/errors detected.
 
-guide:
-	$(MAKE) -C guide kea-guide.html
-
-pdf:
-	$(MAKE) -C guide kea-guide.pdf
-
-pages:
-	$(MAKE) -C guide pages
-
 clean:
 	rm -rf html
 

doc/guide/Makefile.am

+if GENERATE_DOCS
+# TODO
+#HTMLDOCS = kea-guide.html kea-messages.html
+#DOCS = kea-guide.txt
 
-rst_sources=admin.rst
+#dist_doc_DATA = $(DOCS)
+#dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png
+#dist_html_DATA = $(HTMLDOCS) _static/kea-logo-100x70.png
+
+#doc_DATA = _build/singlehtml/kea-guide.html _build/singlehtml/_static/kea-logo-100x70.png
+
+rst_sources=
+rst_sources+=kea-messages.rst
+rst_sources+=admin.rst
 rst_sources+=agent.rst
 rst_sources+=api.rst
 rst_sources+=classify.rst
@@ -20,9 +32,9 @@ rst_sources+=hooks-radius.rst
 rst_sources+=hooks.rst
 rst_sources+=hooks-stat-cmds.rst
 rst_sources+=install.rst
+rst_sources+=index.rst
 rst_sources+=intro.rst
 rst_sources+=keactrl.rst
-rst_sources+=kea-guide.rst
 rst_sources+=lease-expiration.rst
 rst_sources+=lfc.rst
 rst_sources+=logging.rst
@@ -31,8 +43,50 @@ rst_sources+=quickstart.rst
 rst_sources+=shell.rst
 rst_sources+=stats.rst
 
+static_sources=
+static_sources+=_static/kea-imageonly-100bw.png
+static_sources+=_static/kea-logo-200.png
+static_sources+=_static/kea.css
+
+all_sources=$(rst_sources) conf.py $(static_sources)
+
+
+EXTRA_DIST = $(all_sources) $(top_srcdir)/tools/system_messages.py
+
+DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
+
+CLEANFILES = kea-guide.pdf kea-messages.pdf
+
+mes_files=
+mes_files+=$(top_srcdir)/src/hooks/dhcp/mysql_cb/mysql_cb_messages.mes
+mes_files+=$(top_srcdir)/src/hooks/dhcp/lease_cmds/lease_cmds_messages.mes
+mes_files+=$(top_srcdir)/src/hooks/dhcp/high_availability/ha_messages.mes
+mes_files+=$(top_srcdir)/src/hooks/dhcp/stat_cmds/stat_cmds_messages.mes
+mes_files+=$(top_srcdir)/src/hooks/dhcp/user_chk/user_chk_messages.mes
+mes_files+=$(top_srcdir)/src/lib/config/config_messages.mes
+mes_files+=$(top_srcdir)/src/lib/hooks/hooks_messages.mes
+mes_files+=$(top_srcdir)/src/lib/dhcpsrv/dhcpsrv_messages.mes
+mes_files+=$(top_srcdir)/src/lib/dhcpsrv/alloc_engine_messages.mes
+mes_files+=$(top_srcdir)/src/lib/dhcpsrv/hosts_messages.mes
+mes_files+=$(top_srcdir)/src/lib/http/http_messages.mes
+mes_files+=$(top_srcdir)/src/lib/dhcp_ddns/dhcp_ddns_messages.mes
+mes_files+=$(top_srcdir)/src/lib/database/db_messages.mes
+mes_files+=$(top_srcdir)/src/lib/log/log_messages.mes
+mes_files+=$(top_srcdir)/src/lib/log/logimpl_messages.mes
+mes_files+=$(top_srcdir)/src/lib/log/tests/log_test_messages.mes
+mes_files+=$(top_srcdir)/src/lib/process/process_messages.mes
+mes_files+=$(top_srcdir)/src/lib/asiodns/asiodns_messages.mes
+mes_files+=$(top_srcdir)/src/lib/eval/eval_messages.mes
+mes_files+=$(top_srcdir)/src/bin/dhcp4/dhcp4_messages.mes
+mes_files+=$(top_srcdir)/src/bin/agent/ca_messages.mes
+mes_files+=$(top_srcdir)/src/bin/d2/d2_messages.mes
+mes_files+=$(top_srcdir)/src/bin/dhcp6/dhcp6_messages.mes
+mes_files+=$(top_srcdir)/src/bin/lfc/lfc_messages.mes
+mes_files+=$(top_srcdir)/src/bin/netconf/netconf_messages.mes
+
+kea-messages.rst: $(mes_files) $(top_srcdir)/tools/system_messages.py
+	$(top_srcdir)/tools/system_messages.py -o $@ $(mes_files)
 
-sphinxbuild = sphinx-build
 
 sphinxopts=
 sphinxopts+=-v
@@ -44,21 +98,28 @@ sphinxopts+=-D version="@PACKAGE_VERSION@"
 
 sphinxbuilddir=$(builddir)/_build
 
-all: pdf html singlehtml
+all: pdf html
 
-pdf: $(rst_sources)
-	$(sphinxbuild) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts)
+pdf: $(all_sources)
+	$(SPHINXBUILD) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts)
 
-html singlehtml: $(rst_sources)
-	$(sphinxbuild) -M $@ $(srcdir) $(sphinxbuilddir) $(sphinxopts)
+html: $(all_sources)
+	$(SPHINXBUILD) -M $@ $(srcdir) $(sphinxbuilddir) $(sphinxopts)
 
 
-EXTRA_DIST = $(rst_sources)
+install-data-local:
+	mkdir -p $(DESTDIR)$(docdir)
+	cp -r $(sphinxbuilddir)/html $(DESTDIR)$(docdir)
+	cp -r $(sphinxbuilddir)/latex/KeaAdministratorReferenceManual.pdf $(DESTDIR)$(docdir)
 
-# TODO: here should be added some stuff for DIST, etc to be consumed by automake/autoconf
+uninstall-local:
+	rm -rf $(DESTDIR)$(docdir)
 
 clean::
 	-rm -rf $(sphinxbuilddir)
 
 
-.PHONY: all pdf html singlehtml
+.PHONY: all pdf html
+
+
+endif

doc/guide/conf.py

@@ -46,7 +46,10 @@ templates_path = ['_templates']
 source_suffix = '.rst'
 
 # The master toctree document.
-master_doc = 'kea-guide'
+master_doc = 'index'
+
+# Additional docs
+messages_doc = 'kea-messages'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -71,14 +74,16 @@ pygments_style = None
 #
 #html_theme = 'alabaster'
 html_theme = 'sphinx_rtd_theme'
+#html_logo = '_static/kea-logo-100x70.png'
+html_logo = '_static/kea-imageonly-100bw.png'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {
-    "logo": "kea-logo-100x70.png",
-}
+#html_theme_options = {
+#    "logo": "kea-logo-100x70.png",
+#}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -126,8 +131,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'KeaAdministratorReferenceManual.tex', 'Kea Administrator Reference Manual Documentation',
-     'Kea Team', 'manual'),
+    (master_doc, 'KeaAdministratorReferenceManual.tex', 'Kea Administrator Reference Manual Documentation', author, 'manual'),
+    (messages_doc, 'KeaMessages.tex', 'Kea Messages Manual', author, 'manual'),
 ]
 
 

doc/guide/kea-guide.rst → doc/guide/index.rst

+.. figure:: _static/kea-logo-200.png
+   :align: right
+
 ##################################
 Kea Administrator Reference Manual
 ##################################

tools/system_messages.py

+#!/usr/bin/env python3
+
+# Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http:#mozilla.org/MPL/2.0/.
+
+# Produce System Messages Manual
+#
+# This tool reads all the message files given on the command line.
+# It pulls all the messages and description out, sorts them by
+# message ID, and writes them out as a single (formatted) file.
+#
+# Invocation:
+# The code is invoked using the command line:
+#
+# system_messages.py [-o <output-file>] <files>
+#
+# If no output file is specified, output is written to stdout.
+# The produced format is ReStructuredText.
+
+import re
+import argparse
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description='Convert set of *.mes files to .rst documentation format')
+    parser.add_argument('-o', '--output', help='Output file name (default to stdout).')
+    parser.add_argument('files', help='Input .mes files.', nargs='+') #, required=True)
+
+    args = parser.parse_args()
+    return args
+
+
+def read_input_files(files):
+    messages = {}
+    for f in files:
+        with open(f) as fp:
+            namespace = None
+            msg_descr = None
+            msg_id = None
+            msg_text = None
+            for line in fp.readlines():
+                line = line.strip()
+
+                if not line or line.startswith('#'):
+                    pass
+
+                elif line.startswith('$'):
+                    pass
+
+                elif line.startswith('%'):
+                    # end previous message
+                    if msg_id is not None:
+                        section = msg_id.split('_')[0]
+                        messages[msg_id] = (section, msg_id, msg_text, msg_descr)
+
+                    # start next message
+                    m = re.search('^%\s?([A-Z0-9_]+)\s+(.*)', line);
+                    msg_id, msg_text = m.groups()
+                    msg_descr = []
+
+                else:
+                    msg_descr.append(line)
+
+    return messages
+
+
+def generate_rst(messages):
+    rst = '''
+###################
+Kea Messages Manual
+###################
+
+Kea is an open source implementation of the Dynamic Host Configuration
+Protocol (DHCP) servers, developed and maintained by Internet Systems
+Consortium (ISC).
+
+This is the reference guide for Kea version |release|.
+Links to the most up-to-date version of this document (in PDF, HTML,
+and plain text formats), along with other documents for
+Kea, can be found in ISC's `Knowledgebase <https://kb.isc.org/docs/kea-administrator-reference-manual>`_.
+
+
+.. toctree::
+   :numbered:
+   :maxdepth: 5
+
+'''
+
+    prev_section = None
+    for _, msg in sorted(messages.items()):
+        section, msg_id, msg_text, msg_descr = msg
+
+        if section != prev_section:
+            prev_section = section
+            rst += section + '\n'
+            rst += '~' * len(section) + '\n\n'
+
+        rst += '**' + msg_id + '**\n\n'
+
+        rst += msg_text + '\n\n'
+
+        rst += ''.join(['  ' + l + '\n' for l in msg_descr])
+        rst += '\n'
+
+
+    return rst
+
+def main():
+    args = parse_args()
+
+    messages = read_input_files(args.files)
+
+    rst = generate_rst(messages)
+
+    if args.output:
+        with open(args.output, 'w') as f:
+            f.write(rst)
+    else:
+        print(rst)
+
+if __name__ == '__main__':
+    main()