krb5 commit: Fix doc issues with newer Doxygen and Sphinx

https://github.com/krb5/krb5/commit/281210909beef4683be3b63bc1ac1e75c2c9c7eb
commit 281210909beef4683be3b63bc1ac1e75c2c9c7eb
Author: Greg Hudson <[email protected]>
Date:   Tue Sep 22 11:32:00 2020 -0400

    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)

 doc/_templates/layout.html     |    1 -
 doc/conf.py                    |    7 ++--
 doc/tools/doxybuilder_types.py |    7 +++-
 doc/tools/func_document.tmpl   |    2 +-
 src/include/krb5/krb5.hin      |   70 ++++++++++++++++++++--------------------
 5 files changed, 44 insertions(+), 43 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
diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index 9927d2f..045334a 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -254,7 +254,7 @@ typedef krb5_principal_data * krb5_principal;
 #define KRB5_NT_MS_PRINCIPAL_AND_ID  -129 /**< NT 4 style name */
 #define KRB5_NT_ENT_PRINCIPAL_AND_ID -130 /**< NT 4 style name and SID */
 
-/** Constant version of krb5_principal_data */
+/** Constant version of krb5_principal_data. */
 typedef const krb5_principal_data *krb5_const_principal;
 
 #define krb5_princ_realm(context, princ) (&(princ)->realm)
@@ -1944,7 +1944,7 @@ typedef struct _krb5_ticket_times {
 typedef struct _krb5_authdata {
     krb5_magic magic;
     krb5_authdatatype ad_type; /**< ADTYPE */
-    unsigned int length;       /**< Length of data  */
+    unsigned int length;       /**< Length of data */
     krb5_octet *contents;      /**< Data */
 } krb5_authdata;
 
@@ -2134,7 +2134,7 @@ typedef struct _krb5_ap_rep {
     krb5_enc_data enc_part;     /**< Ciphertext of ApRepEncPart */
 } krb5_ap_rep;
 
-/** Cleartext that is encrypted and put into @c _krb5_ap_rep.  */
+/** Cleartext that is encrypted and put into @c _krb5_ap_rep. */
 typedef struct _krb5_ap_rep_enc_part {
     krb5_magic magic;
     krb5_timestamp ctime;       /**< Client time, seconds portion */
@@ -2163,7 +2163,7 @@ typedef struct _krb5_cred_info {
     krb5_address **caddrs;      /**< Array of pointers to addrs (optional) */
 } krb5_cred_info;
 
-/** Cleartext credentials information.  */
+/** Cleartext credentials information. */
 typedef struct _krb5_cred_enc_part {
     krb5_magic magic;
     krb5_int32 nonce;           /**< Nonce (optional) */
@@ -2244,14 +2244,14 @@ typedef struct _krb5_pa_pac_req {
 typedef struct krb5_replay_data {
     krb5_timestamp      timestamp;  /**< Timestamp, seconds portion */
     krb5_int32          usec;       /**< Timestamp, microseconds portion */
-    krb5_ui_4           seq;        /**< Sequence number  */
+    krb5_ui_4           seq;        /**< Sequence number */
 } krb5_replay_data;
 
 /* Flags for krb5_auth_con_genaddrs(). */
 
 /** Generate the local network address. */
 #define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR       0x00000001
-/** Generate the remote network address.  */
+/** Generate the remote network address. */
 #define KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR      0x00000002
 /** Generate the local network address and the local port. */
 #define KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR  0x00000004
@@ -6423,7 +6423,7 @@ krb5_deltat_to_string(krb5_deltat deltat, char *buffer, size_t buflen);
 #define KRB5_RECVAUTH_BADAUTHVERS       0x0002
 /* initial ticket api functions */
 
-/** Text for prompt used in prompter callback function.  */
+/** Text for prompt used in prompter callback function. */
 typedef struct _krb5_prompt {
     char *prompt;      /**< The prompt to show to the user */
     int hidden;        /**< Boolean; informative prompt or hidden (e.g. PIN) */
@@ -6483,29 +6483,29 @@ krb5_prompter_posix(krb5_context context, void *data, const char *name,
  * value is required in order to complete the authentication.  The JSON format
  * of the challenge is:
  *
- *  @n {
- *  @n   "service": <string (optional)>,
- *  @n   "tokenInfo": [
- *  @n      {
- *  @n        "flags":     <number>,
- *  @n        "vendor":    <string (optional)>,
- *  @n        "challenge": <string (optional)>,
- *  @n        "length":    <number (optional)>,
- *  @n        "format":    <number (optional)>,
- *  @n        "tokenID":   <string (optional)>,
- *  @n        "algID":     <string (optional)>,
- *  @n      },
- *  @n      ...
- *  @n    ]
- *  @n  }
+ *     {
+ *       "service": <string (optional)>,
+ *       "tokenInfo": [
+ *         {
+ *           "flags":     <number>,
+ *           "vendor":    <string (optional)>,
+ *           "challenge": <string (optional)>,
+ *           "length":    <number (optional)>,
+ *           "format":    <number (optional)>,
+ *           "tokenID":   <string (optional)>,
+ *           "algID":     <string (optional)>,
+ *         },
+ *         ...
+ *       ]
+ *     }
  *
  * The answer to the question MUST be JSON formatted:
  *
- * @n  {
- * @n    "tokeninfo": <number>,
- * @n    "value":     <string (optional)>,
- * @n    "pin":       <string (optional)>,
- * @n  }
+ *     {
+ *       "tokeninfo": <number>,
+ *       "value":     <string (optional)>,
+ *       "pin":       <string (optional)>,
+ *     }
  *
  * For more detail, please see RFC 6560.
  *
@@ -6556,17 +6556,17 @@ krb5_prompter_posix(krb5_context context, void *data, const char *name,
  * below, and possibly other flags to be added later.  Any resemblance to
  * similarly-named CKF_* values in the PKCS#11 API should not be depended on.
  *
- *  @n {
- *  @n     identity <string> : flags <number>,
- *  @n     ...
- *  @n }
+ *     {
+ *         identity <string> : flags <number>,
+ *         ...
+ *     }
  *
  * The answer to the question MUST be JSON formatted:
  *
- *  @n {
- *  @n     identity <string> : password <string>,
- *  @n     ...
- *  @n }
+ *     {
+ *         identity <string> : password <string>,
+ *         ...
+ *     }
  *
  * @version New in 1.12
  */