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)

diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index f20a43b96c5bc616b8655ce9fb3a6d4b1e70b159..f05b91921ed49eac1147c7be4620b7cb50259942 100644 (file)
--- 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 c32b2882afc2c4092c24411f2775c0e4beed1374..9226b8e0150536f4d2466b8b2470ca11d5758b69 100644 (file)
--- 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 947971a94db37faa71ed7673fa070428eefbe2f4..bdab120d6c373bf7f5b78774674261af6995bf6b 100644 (file)
--- 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 49860589f8fad001397468afcffee197999c5a9b..104930b6354bb638e1f8f45b28172e64116313d3 100644 (file)
--- 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 9927d2f58c2ff8457d540180224e7e90feb546a6..045334a083e736450e71ac4d0d10d313eb301cda 100644 (file)
--- 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
  */