Fix doc issues with newer Doxygen and Sphinx

In krb5.hin, fix some apparently harmless whitespace nits in comments
which cause newer Doxygen versions to generate <detaileddescription>
content containing <linebreak/> tags.  Also remove the explicit "@n"
linebreaks in the responder JSON schemas, instead relying on Doxygen
markup support (added in Doxygen 1.8).  Add a verbatim handler in
doxybuilder_types.py to translate the resulting section, replacing the
linebreak handler which is no longer needed.

css_files is deprecated in Sphinx.  Instead use app.add_stylesheet()
in a setup function in conf.py.  (Sphinx 1.8 has a slightly simpler
method, but that is currently too recent to depend on.)  Also remove
the obsolete html_use_smartypants setting.

In func_document.tmpl, fix an incorrent use of "is".

ticket: 8952 (new)

4 files changed, 9 insertions, 8 deletions

diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index f20a43b..f05b919 100644
--- a/doc/_templates/layout.html
+++ b/doc/_templates/layout.html
@@ -2,7 +2,6 @@
 {% set rellinks = [('search', 'Enter search criteria', 'S', 'Search')] +
                   rellinks +
                   [('index', 'Full Table of Contents', 'C', 'Contents')] %}
-{% set css_files = css_files + ["_static/kerb.css"] %}
 
 {# Add a "feedback" button to the rellinks #}
 {%- macro feedback_rellinks() %}
diff --git a/doc/conf.py b/doc/conf.py
index c32b288..9226b8e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -98,6 +98,9 @@ pygments_style = 'sphinx'
 
 # -- Options for HTML output ---------------------------------------------------
 
+def setup(app):
+    app.add_stylesheet('kerb.css')
+
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 # html_theme = 'default'
@@ -139,10 +142,6 @@ html_static_path = ['_static']
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
 
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-html_use_smartypants = True
-
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
diff --git a/doc/tools/doxybuilder_types.py b/doc/tools/doxybuilder_types.py
index 947971a..bdab120 100644
--- a/doc/tools/doxybuilder_types.py
+++ b/doc/tools/doxybuilder_types.py
@@ -25,6 +25,7 @@
 import sys
 import os
 import re
+import textwrap
 
 from lxml import etree
 
@@ -293,8 +294,10 @@ class DoxyTypes(object):
                     result.append('*%s*' % e.strip())
             elif  e.getparent().tag == 'defname':
                 result.append('%s, ' % e.strip())
-            elif  e.getparent().tag == 'linebreak':
-                result.append('\n*%s*\n' % e.strip())
+            elif e.getparent().tag == 'verbatim':
+                result.append('\n::\n\n')
+                result.append(textwrap.indent(e, '    ', lambda x: True))
+                result.append('\n')
 
         result = ' '.join(result)
 
diff --git a/doc/tools/func_document.tmpl b/doc/tools/func_document.tmpl
index 4986058..104930b 100644
--- a/doc/tools/func_document.tmpl
+++ b/doc/tools/func_document.tmpl
@@ -16,7 +16,7 @@ $title
 :param:
 
 #for $param in $function.parameters:
-	#if $param.name is ''
+	#if $param.name == ''
 		#continue
 	#end if
 	#if $param.direction is not None