From: Greg Hudson Date: Tue, 22 Sep 2020 15:32:00 +0000 (-0400) Subject: Fix doc issues with newer Doxygen and Sphinx X-Git-Tag: krb5-1.19-beta1~24 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F1119%2Fhead;p=thirdparty%2Fkrb5.git 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 content containing 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 f20a43b96c..f05b91921e 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 c32b2882af..9226b8e015 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 947971a94d..bdab120d6c 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 49860589f8..104930b635 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 9927d2f58c..045334a083 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": , - * @n "tokenInfo": [ - * @n { - * @n "flags": , - * @n "vendor": , - * @n "challenge": , - * @n "length": , - * @n "format": , - * @n "tokenID": , - * @n "algID": , - * @n }, - * @n ... - * @n ] - * @n } + * { + * "service": , + * "tokenInfo": [ + * { + * "flags": , + * "vendor": , + * "challenge": , + * "length": , + * "format": , + * "tokenID": , + * "algID": , + * }, + * ... + * ] + * } * * The answer to the question MUST be JSON formatted: * - * @n { - * @n "tokeninfo": , - * @n "value": , - * @n "pin": , - * @n } + * { + * "tokeninfo": , + * "value": , + * "pin": , + * } * * 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 : flags , - * @n ... - * @n } + * { + * identity : flags , + * ... + * } * * The answer to the question MUST be JSON formatted: * - * @n { - * @n identity : password , - * @n ... - * @n } + * { + * identity : password , + * ... + * } * * @version New in 1.12 */