krb5 commit: Fix doc issues with newer Doxygen and Sphinx
Greg Hudson
ghudson at mit.edu
Mon Sep 28 22:41:56 EDT 2020
https://github.com/krb5/krb5/commit/281210909beef4683be3b63bc1ac1e75c2c9c7eb
commit 281210909beef4683be3b63bc1ac1e75c2c9c7eb
Author: Greg Hudson <ghudson at mit.edu>
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
*/
More information about the cvs-krb5
mailing list