Skip Menu |
 

Subject: Fix warnings in doc build
There are several "document isn't included in any toctree" warnings that we can ignore, but
others about "reference to nonexisting document" , "unknown target name", "block quote ends
without a blank line", etc., may need to be addressed.
I'll also put a few fixes that I found while working on this ticket in the same ticket.
Some commits had needed changes that were preempted by other commits to the main repo,
etc..
From: kaduk@MIT.EDU
Subject: SVN Commit

Use en dash instead of hyphen

It should not be bracketed in whitespace.

https://github.com/krb5/krb5/commit/22288fd3933830eaa76a8f9b0d1432d072a1fac3
Author: Ben Kaduk <kaduk@mit.edu>
Commit: 22288fd3933830eaa76a8f9b0d1432d072a1fac3
Branch: master
doc/mitK5features.rst | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
From: kaduk@MIT.EDU
Subject: SVN Commit

Make krb5_trace_info a typedef

Our doxygen-to-sphinx documentation bridge only processes typedefs
and not structure definitions, since we almost universally use
typedefs for our data structures. krb5_trace_info is the sole
exception, so bring it into the fold.

While here, flesh out the comment a bit more.

https://github.com/krb5/krb5/commit/6a019d5cff9aecb88591accf03ac737c6f910c69
Author: Ben Kaduk <kaduk@mit.edu>
Commit: 6a019d5cff9aecb88591accf03ac737c6f910c69
Branch: master
src/include/krb5/krb5.hin | 16 +++++++++++-----
src/lib/krb5/os/trace.c | 4 ++--
2 files changed, 13 insertions(+), 7 deletions(-)
From: kaduk@MIT.EDU
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.7KiB

Update doxygen markup in krb5.hin

A few places were using the standard C /* comment */ form, but
this is rendered poorly by doxygen through to our Sphinx bridge.
Use the special /**< comment */ form to get doxygen-specific behavior.
If the standard C comment form is used, the full comment (including
start and end markers) is included in the value of the macro, and
Sphinx then tries to treat the end of the comment as the start of
inline markup with no corresponding end-string, which is a warning.
Using the doxygen form of the comment, the contents of the comment
are put in a separate paragraph block, which is inserted in the
body of the generated RST document.

The markup for krb5_rd_priv() had a line that ended with an @c
markup statement without a symbol following it. This confused
doxygen into not parsing any more of the comment. The beginning
of the next line is a macro identifier with markup to auto-linkify it.
In RST, it is not possible to have a link and a terminal font on the
same text, so removing the @c is the appropriate fix.

There are also eleven deprecated functions which are replaced by
the krb5_c_* family of functions. However, referring to this class
of functions as the "krb5_c_" class of functions results in Sphinx
attempting to interpret this statement as a link to a label elsewhere
in the document, and no such label exists. To avoid this warning, use
"krb5_c_*" to refer to the class of functions, which is arguably
more correct anyways.

https://github.com/krb5/krb5/commit/3070dcd18ea2d07f74afa35fa4a8cada373d9975
Author: Ben Kaduk <kaduk@mit.edu>
Commit: 3070dcd18ea2d07f74afa35fa4a8cada373d9975
Branch: master
src/include/krb5/krb5.hin | 40 ++++++++++++++++++++--------------------
1 files changed, 20 insertions(+), 20 deletions(-)
From: kaduk@MIT.EDU
Subject: SVN Commit

Fix overflowing cell in HTML table

sphinx-build defaults to the 'tabulary' environment for tables,
but uses regular 'tabular' for those involving literal blocks,
since tabulary does not handle them properly. It seems that this
deficiency of tabulary also applies to inline literals, which
are rendered as \code{} sections by the latex builder.
Fortunately, sphinx provides a workaround to force a particular
column specification for the table.

The requirement for a table:: statement after the tabularcolumns::
statement is very poorly documented.

https://github.com/krb5/krb5/commit/da396d7603e949faec594036dee6de0e8f44bddb
Author: Ben Kaduk <kaduk@mit.edu>
Commit: da396d7603e949faec594036dee6de0e8f44bddb
Branch: master
doc/appdev/h5l_mit_apidiff.rst | 3 +++
1 files changed, 3 insertions(+), 0 deletions(-)
From: kaduk@MIT.EDU
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.4KiB

Handle adjacent notes from doxygen more correctly

The Doxygen documentation seems to claim that adjacent @note entries
will be collapsed into a single "note" element, as separate paragraphs.
This seems to be reflected in the XML output: multiple <para> entries
in a single <simplesec kind="note"> with a <simplesecsep/> element
between them.

Our XML-to-RST converter gets the entire contents of the simplesec
element, parsed into a unicode string with a single newline between
paragraphs. Paragraphs seem to always start with two spaces, though
I have not tracked down the origin of this behavior. Prior to this
commit, we would just output this entire unicode string directly.
Since our template puts a tab character before the note string, this
means that the first paragraph is indented by a tab and two spaces,
and the second paragraph by just two spaces. Sphinx warns about this,
as "block did not end with blank line; unexpected whitespace", and
the paragraphs are indented differently within the note.

Fix the warning by checking for newlines in the interior of the
parsed unicode string, and introducing the appropriate whitespace
for the Sphinx parser.

https://github.com/krb5/krb5/commit/484ac9228b317b96a81c9e88778c521c54d49213
Author: Ben Kaduk <kaduk@mit.edu>
Commit: 484ac9228b317b96a81c9e88778c521c54d49213
Branch: master
doc/tools/doxybuilder_funcs.py | 3 ++-
1 files changed, 2 insertions(+), 1 deletions(-)
From: kaduk@MIT.EDU
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.3KiB

Exclude lists for doxygen API docs

Doxygen will pick up every function, macro, and typedef defined
in krb5.h; some of these may not actually be part of the public
API for one reason or another. Provide hardcoded exclude lists
for macro/function/type names for which we do not want to emit
reStructuredText documentation, and check these lists when processing
the Doxygen XML output.

Seed these lists with the macros TRUE, FALSE, KRB5_OLD_CRYPTO,
KRB5_GENERAL__, KRB5_CALLCONV, KRB5_CALLCONV_C, KRB5_CALLCONV_WRONG,
KRB5INT_BEGIN_DECLS, KRB5INT_END_DECLS, and KRB5_ATTR_DEPRECATED,
and typedefs krb5_cc_ops and krb5_responder_context. The booleans
are compatibility cruft that we do not want to advertise, and the other
macros are for internal use for signalling and platform compatibility.
The typedefs are functioning just as forward declarations.

For consistency, remove KRB5_OLD_CRYPTO.rst from the macros index; it
had no content even when we did generate it.

https://github.com/krb5/krb5/commit/f17cc2c9edc4f36c96391d438ddeaf5bab5b2b65
Author: Ben Kaduk <kaduk@mit.edu>
Commit: f17cc2c9edc4f36c96391d438ddeaf5bab5b2b65
Branch: master
doc/appdev/refs/macros/index.rst | 1 -
doc/tools/doxybuilder_funcs.py | 4 ++++
doc/tools/doxybuilder_types.py | 7 +++++++
3 files changed, 11 insertions(+), 1 deletions(-)
From: kaduk@MIT.EDU
Subject: SVN Commit

Handle multiline macro definitions

Compress them onto one line for printing in the generated table.

https://github.com/krb5/krb5/commit/760155906bc47163bac1fb5622034a9d53e15294
Author: Ben Kaduk <kaduk@mit.edu>
Commit: 760155906bc47163bac1fb5622034a9d53e15294
Branch: master
doc/tools/doxybuilder_types.py | 2 ++
1 files changed, 2 insertions(+), 0 deletions(-)
From: kaduk@MIT.EDU
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.3KiB

Render macros as literals

Some convenience macros are referring to and dereferencing pointers,
and Sphinx will get a bit confused trying to interpret this as markup.
There should never be any markup intended to be interpreted in the
value of a macro definition, so we can silence this class of
warnings by treating them as literals. (In some sense, they actually
are literals, too.)

This will cause a warning for macros that only cause a
symbol to be defined, that is, a literal "#define MACRO" with no
initializer, due to the lack of body in the inline-literal markup.
Such macros should probably be added to the exclude list for conversion
to reStructuredText in the Doxygen-Sphinx bridge, as was already
done for KRB5_OLD_CRYPTO. Support code to programmatically omit
macros of this sort is deliberately *not* included, so that explicit
action must be taken when a new macro is to be undocumented.

Also, strip leading and trailing whitespace from the macro name,
since this causes problems with the markup.

https://github.com/krb5/krb5/commit/94947241bd347e9b4dd729c5d550150b7e8cd64c
Author: Ben Kaduk <kaduk@mit.edu>
Commit: 94947241bd347e9b4dd729c5d550150b7e8cd64c
Branch: master
doc/tools/define_document.tmpl | 12 ++++++------
doc/tools/doxybuilder_types.py | 2 +-
2 files changed, 7 insertions(+), 7 deletions(-)
From: kaduk@MIT.EDU
Subject: SVN Commit

Remove last "document not in toctree" warnings

There were two of them, for notice.rst and mitK5license.rst.
The former is included in the latter, which is linked to from
the mitK5features document but not listed in a table of contents
otherwise. Includes are processed unconditionally, so we can
add notice.rst to the exclude_patterns array (formerly unused_docs)
and its content will still be included.

If we attempt to do the same for mitK5license.rst, it is not processed
at all, and the attempt to link to it will fail. Instead, put a dummy
table of contents in the mitK5features document (which links to the
license document), with the "hidden" attribute. This satisfies the
Sphinx need to know where all the input documents are without changing
the displayed table of contents.

https://github.com/krb5/krb5/commit/b358b505be4502a71495ce58b8444027121726ee
Author: Ben Kaduk <kaduk@mit.edu>
Commit: b358b505be4502a71495ce58b8444027121726ee
Branch: master
doc/conf.py | 1 +
doc/mitK5features.rst | 5 +++++
2 files changed, 6 insertions(+), 0 deletions(-)
Download (untitled) / with headers
text/plain 1.2KiB
[kaduk@MIT.EDU - Tue Nov 27 18:02:34 2012]:

Show quoted text
>
> Remove last "document not in toctree" warnings
>
> There were two of them, for notice.rst and mitK5license.rst.
> The former is included in the latter, which is linked to from
> the mitK5features document but not listed in a table of contents
> otherwise. Includes are processed unconditionally, so we can
> add notice.rst to the exclude_patterns array (formerly unused_docs)
> and its content will still be included.
>
> If we attempt to do the same for mitK5license.rst, it is not processed
> at all, and the attempt to link to it will fail. Instead, put a dummy
> table of contents in the mitK5features document (which links to the
> license document), with the "hidden" attribute. This satisfies the
> Sphinx need to know where all the input documents are without changing
> the displayed table of contents.
>
> https://github.com/krb5/krb5/commit/b358b505be4502a71495ce58b8444027121726ee
> Author: Ben Kaduk <kaduk@mit.edu>
> Commit: b358b505be4502a71495ce58b8444027121726ee
> Branch: master
> doc/conf.py | 1 +
> doc/mitK5features.rst | 5 +++++
> 2 files changed, 6 insertions(+), 0 deletions(-)

Now MIT Kerberos License information appears in the sidebar which is undesirable behavior.
Date: Wed, 28 Nov 2012 11:37:36 -0500 (EST)
From: Benjamin Kaduk <kaduk@MIT.EDU>
To: Zhanna Tsitkova via RT <rt-comment@krbdev.MIT.EDU>
Subject: Re: [krbdev.mit.edu #7447] Fix warnings in doc build
RT-Send-Cc:
Download (untitled) / with headers
text/plain 1.4KiB
On Wed, 28 Nov 2012, Zhanna Tsitkova via RT wrote:

Show quoted text
> [kaduk@MIT.EDU - Tue Nov 27 18:02:34 2012]:
>
>>
>> Remove last "document not in toctree" warnings
>>
>> There were two of them, for notice.rst and mitK5license.rst.
>> The former is included in the latter, which is linked to from
>> the mitK5features document but not listed in a table of contents
>> otherwise. Includes are processed unconditionally, so we can
>> add notice.rst to the exclude_patterns array (formerly unused_docs)
>> and its content will still be included.
>>
>> If we attempt to do the same for mitK5license.rst, it is not processed
>> at all, and the attempt to link to it will fail. Instead, put a dummy
>> table of contents in the mitK5features document (which links to the
>> license document), with the "hidden" attribute. This satisfies the
>> Sphinx need to know where all the input documents are without changing
>> the displayed table of contents.
>>
>> https://github.com/krb5/krb5/commit/b358b505be4502a71495ce58b8444027121726ee
>> Author: Ben Kaduk <kaduk@mit.edu>
>> Commit: b358b505be4502a71495ce58b8444027121726ee
>> Branch: master
>> doc/conf.py | 1 +
>> doc/mitK5features.rst | 5 +++++
>> 2 files changed, 6 insertions(+), 0 deletions(-)
>
> Now MIT Kerberos License information appears in the sidebar which is undesirable behavior.

Hmm, this may be a Sphinx bug, I'll try to look and see.

Why is it undesirable to have the license information in the sidebar?

-Ben
Date: Wed, 28 Nov 2012 13:42:54 -0500 (EST)
From: Benjamin Kaduk <kaduk@MIT.EDU>
To: Zhanna Tsitkova via RT <rt-comment@krbdev.MIT.EDU>
Subject: Re: [krbdev.mit.edu #7447] Fix warnings in doc build
RT-Send-Cc:
On Wed, 28 Nov 2012, Benjamin Kaduk wrote:

Show quoted text
> On Wed, 28 Nov 2012, Zhanna Tsitkova via RT wrote:
>
>> [kaduk@MIT.EDU - Tue Nov 27 18:02:34 2012]:
>>
>> Now MIT Kerberos License information appears in the sidebar which is
>> undesirable behavior.
>
> Hmm, this may be a Sphinx bug, I'll try to look and see.

Not actually a current sphinx bug; it was fixed for 0.6.x. We just need
to use an undocumented option as in
https://github.com/kaduk/krb5/commit/bc8a7c4

Show quoted text
> Why is it undesirable to have the license information in the sidebar?

I still would like to know this.

-Ben
From: Zhanna Tsitkov <tsitkova@MIT.EDU>
To: "<rt-comment@krbdev.mit.edu>" <rt-comment@krbdev.mit.edu>
Subject: Re: [krbdev.mit.edu #7447] Fix warnings in doc build
Date: Wed, 28 Nov 2012 21:36:34 +0000
RT-Send-Cc:
Download (untitled) / with headers
text/plain 2.1KiB

On Nov 28, 2012, at 11:37 AM, Benjamin Kaduk via RT wrote:

Show quoted text
> On Wed, 28 Nov 2012, Zhanna Tsitkova via RT wrote:
>
>> [kaduk@MIT.EDU - Tue Nov 27 18:02:34 2012]:
>>
>>>
>>> Remove last "document not in toctree" warnings
>>>
>>> There were two of them, for notice.rst and mitK5license.rst.
>>> The former is included in the latter, which is linked to from
>>> the mitK5features document but not listed in a table of contents
>>> otherwise. Includes are processed unconditionally, so we can
>>> add notice.rst to the exclude_patterns array (formerly unused_docs)
>>> and its content will still be included.
>>>
>>> If we attempt to do the same for mitK5license.rst, it is not processed
>>> at all, and the attempt to link to it will fail. Instead, put a dummy
>>> table of contents in the mitK5features document (which links to the
>>> license document), with the "hidden" attribute. This satisfies the
>>> Sphinx need to know where all the input documents are without changing
>>> the displayed table of contents.
>>>
>>> https://github.com/krb5/krb5/commit/b358b505be4502a71495ce58b8444027121726ee
>>> Author: Ben Kaduk <kaduk@mit.edu>
>>> Commit: b358b505be4502a71495ce58b8444027121726ee
>>> Branch: master
>>> doc/conf.py | 1 +
>>> doc/mitK5features.rst | 5 +++++
>>> 2 files changed, 6 insertions(+), 0 deletions(-)
>>
>> Now MIT Kerberos License information appears in the sidebar which is undesirable behavior.
>
> Hmm, this may be a Sphinx bug, I'll try to look and see.

this commit added it as a hidden (i.e. invisible) item to the main pageÂ…. what was the motivation?

Show quoted text
>
> Why is it undesirable to have the license information in the sidebar?

The better question is Why should it be there?
The sidebar is used for easier navigation , not for static information. Yesterday we talked about adding Copyrights notice to the footer. We can link it to the License or have separate tab for License or some other option or leave License info in some more generalized section such as MIT kern features...

Show quoted text
>
> -Ben
>
> _______________________________________________
> krb5-bugs mailing list
> krb5-bugs@mit.edu
> https://mailman.mit.edu/mailman/listinfo/krb5-bugs
Download smime.p7s
application/pkcs7-signature 1.5KiB

Message body not shown because it is not plain text.

Date: Wed, 28 Nov 2012 17:13:57 -0500 (EST)
From: Benjamin Kaduk <kaduk@MIT.EDU>
To: Zhanna Tsitkova via RT <rt-comment@krbdev.MIT.EDU>
Subject: Re: [krbdev.mit.edu #7447] Fix warnings in doc build
RT-Send-Cc:
Download (untitled) / with headers
text/plain 2.8KiB
On Wed, 28 Nov 2012, Zhanna Tsitkova via RT wrote:

Show quoted text
>
> On Nov 28, 2012, at 11:37 AM, Benjamin Kaduk via RT wrote:
>
>
> this commit added it as a hidden (i.e. invisible) item to the main
> page?. what was the motivation?

No, it did not. The commit added the license document as a hidden item to
the *features* page. There is no particular reason why it needed to be
the features page, it could have been the user guide index page, or almost
any other page other than the main index page. (The main index page is
unusable because Sphinx is unwilling to have partially-hidden toctrees on
a single page.)

You ask what the motivation was for adding the license document to any
page's toctree at all. The answer is simple: Sphinx assumes that all
documents will be listed in some toctree, and issues a warning at
build-time if that invariant does not hold. I believe that, just as we
strive to keep our source code free of compiler warnings, we should
endeavour to keep our documentation tree free of compiler warnings.
Sphinx allows us to enforce this behavior with the -W argument, but we
cannot do so while there exist warnings in the build. Adding the features
document to a dummy toctree is the least bad way I know of to eliminate
this warning. The only other options I see involve dramatically
restructuring the way the content is presented.

Do you disagree that we should be warning-free? Do you disagree with my
assessment of this method being the least bad way to eliminate this
particular warning?

Show quoted text
>
>>
>> Why is it undesirable to have the license information in the sidebar?
>
> The better question is Why should it be there?
> The sidebar is used for easier navigation , not for static information.

I don't understand what this sentence means. All of the documentation is
"static information", there are merely links among it internally.

We have a link to the license information from a particular page; what
makes having a link in the sidebar so different? Without any links at
all, the static information contained in the documentation would not be
very useful...

Show quoted text
> Yesterday we talked about adding Copyrights notice to the footer. We can
> link it to the License or have separate tab for License or some other
> option or leave License info in some more generalized section such as
> MIT kern features...

If we add a copyright.rst document, it might be reasonable to include the
license document in a (non-hidden) toctree there; I don't have a good
sense for what a copyright.rst would look like. I don't think the other
options listed would involve a toctree, and therefore would still cause
Sphinx to emit a warning at build time.


Please do note that there is a one-line patch which removes the link to
the license document from the sidebar; I will send that out for review
with another small patchset I have underway.

-Ben
From: Zhanna Tsitkov <tsitkova@MIT.EDU>
To: "<rt-comment@krbdev.mit.edu>" <rt-comment@krbdev.mit.edu>
Subject: Re: [krbdev.mit.edu #7447] Fix warnings in doc build
Date: Wed, 28 Nov 2012 22:46:30 +0000
RT-Send-Cc:
Download smime.p7s
application/pkcs7-signature 1.5KiB

Message body not shown because it is not plain text.

this is all I have asked for. Thanks

On Nov 28, 2012, at 5:14 PM, Benjamin Kaduk via RT wrote:

Show quoted text
Please do note that there is a one-line patch which removes the link to 
the license document from the sidebar; I will send that out for review 
with another small patchset I have underway.

From: tlyu@mit.edu
Subject: SVN Commit

Use en dash instead of hyphen

It should not be bracketed in whitespace.

(cherry picked from commit 22288fd3933830eaa76a8f9b0d1432d072a1fac3)

https://github.com/krb5/krb5/commit/56370f5d566f925f0c8566ab250c42a3b9626845
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: 56370f5d566f925f0c8566ab250c42a3b9626845
Branch: krb5-1.11
doc/mitK5features.rst | 2 +-
1 files changed, 1 insertions(+), 1 deletions(-)
From: tlyu@mit.edu
Subject: SVN Commit

Make krb5_trace_info a typedef

Our doxygen-to-sphinx documentation bridge only processes typedefs
and not structure definitions, since we almost universally use
typedefs for our data structures. krb5_trace_info is the sole
exception, so bring it into the fold.

While here, flesh out the comment a bit more.

(cherry picked from commit 6a019d5cff9aecb88591accf03ac737c6f910c69)

https://github.com/krb5/krb5/commit/5ed3a02859e91b67b289e7419e9433f50bfb1259
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: 5ed3a02859e91b67b289e7419e9433f50bfb1259
Branch: krb5-1.11
src/include/krb5/krb5.hin | 16 +++++++++++-----
src/lib/krb5/os/trace.c | 4 ++--
2 files changed, 13 insertions(+), 7 deletions(-)
From: tlyu@mit.edu
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.8KiB

Update doxygen markup in krb5.hin

A few places were using the standard C /* comment */ form, but
this is rendered poorly by doxygen through to our Sphinx bridge.
Use the special /**< comment */ form to get doxygen-specific behavior.
If the standard C comment form is used, the full comment (including
start and end markers) is included in the value of the macro, and
Sphinx then tries to treat the end of the comment as the start of
inline markup with no corresponding end-string, which is a warning.
Using the doxygen form of the comment, the contents of the comment
are put in a separate paragraph block, which is inserted in the
body of the generated RST document.

The markup for krb5_rd_priv() had a line that ended with an @c
markup statement without a symbol following it. This confused
doxygen into not parsing any more of the comment. The beginning
of the next line is a macro identifier with markup to auto-linkify it.
In RST, it is not possible to have a link and a terminal font on the
same text, so removing the @c is the appropriate fix.

There are also eleven deprecated functions which are replaced by
the krb5_c_* family of functions. However, referring to this class
of functions as the "krb5_c_" class of functions results in Sphinx
attempting to interpret this statement as a link to a label elsewhere
in the document, and no such label exists. To avoid this warning, use
"krb5_c_*" to refer to the class of functions, which is arguably
more correct anyways.

(cherry picked from commit 3070dcd18ea2d07f74afa35fa4a8cada373d9975)

https://github.com/krb5/krb5/commit/21729b8f8120f2eaef1e92951efe20de7372f68b
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: 21729b8f8120f2eaef1e92951efe20de7372f68b
Branch: krb5-1.11
src/include/krb5/krb5.hin | 40 ++++++++++++++++++++--------------------
1 files changed, 20 insertions(+), 20 deletions(-)
From: tlyu@mit.edu
Subject: SVN Commit

Fix overflowing cell in HTML table

sphinx-build defaults to the 'tabulary' environment for tables,
but uses regular 'tabular' for those involving literal blocks,
since tabulary does not handle them properly. It seems that this
deficiency of tabulary also applies to inline literals, which
are rendered as \code{} sections by the latex builder.
Fortunately, sphinx provides a workaround to force a particular
column specification for the table.

The requirement for a table:: statement after the tabularcolumns::
statement is very poorly documented.

(cherry picked from commit da396d7603e949faec594036dee6de0e8f44bddb)

https://github.com/krb5/krb5/commit/993204158b81a6dd3798c308fe3cfa633346a4e1
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: 993204158b81a6dd3798c308fe3cfa633346a4e1
Branch: krb5-1.11
doc/appdev/h5l_mit_apidiff.rst | 3 +++
1 files changed, 3 insertions(+), 0 deletions(-)
From: tlyu@mit.edu
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.5KiB

Handle adjacent notes from doxygen more correctly

The Doxygen documentation seems to claim that adjacent @note entries
will be collapsed into a single "note" element, as separate paragraphs.
This seems to be reflected in the XML output: multiple <para> entries
in a single <simplesec kind="note"> with a <simplesecsep/> element
between them.

Our XML-to-RST converter gets the entire contents of the simplesec
element, parsed into a unicode string with a single newline between
paragraphs. Paragraphs seem to always start with two spaces, though
I have not tracked down the origin of this behavior. Prior to this
commit, we would just output this entire unicode string directly.
Since our template puts a tab character before the note string, this
means that the first paragraph is indented by a tab and two spaces,
and the second paragraph by just two spaces. Sphinx warns about this,
as "block did not end with blank line; unexpected whitespace", and
the paragraphs are indented differently within the note.

Fix the warning by checking for newlines in the interior of the
parsed unicode string, and introducing the appropriate whitespace
for the Sphinx parser.

(cherry picked from commit 484ac9228b317b96a81c9e88778c521c54d49213)

https://github.com/krb5/krb5/commit/c54d1d86d9809f35a4b4f9e4e6ac898c695ed404
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: c54d1d86d9809f35a4b4f9e4e6ac898c695ed404
Branch: krb5-1.11
doc/tools/doxybuilder_funcs.py | 3 ++-
1 files changed, 2 insertions(+), 1 deletions(-)
From: tlyu@mit.edu
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.4KiB

Exclude lists for doxygen API docs

Doxygen will pick up every function, macro, and typedef defined
in krb5.h; some of these may not actually be part of the public
API for one reason or another. Provide hardcoded exclude lists
for macro/function/type names for which we do not want to emit
reStructuredText documentation, and check these lists when processing
the Doxygen XML output.

Seed these lists with the macros TRUE, FALSE, KRB5_OLD_CRYPTO,
KRB5_GENERAL__, KRB5_CALLCONV, KRB5_CALLCONV_C, KRB5_CALLCONV_WRONG,
KRB5INT_BEGIN_DECLS, KRB5INT_END_DECLS, and KRB5_ATTR_DEPRECATED,
and typedefs krb5_cc_ops and krb5_responder_context. The booleans
are compatibility cruft that we do not want to advertise, and the other
macros are for internal use for signalling and platform compatibility.
The typedefs are functioning just as forward declarations.

For consistency, remove KRB5_OLD_CRYPTO.rst from the macros index; it
had no content even when we did generate it.

(cherry picked from commit f17cc2c9edc4f36c96391d438ddeaf5bab5b2b65)

https://github.com/krb5/krb5/commit/6a743c2532656713ba947eccc822a2e26c675d01
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: 6a743c2532656713ba947eccc822a2e26c675d01
Branch: krb5-1.11
doc/appdev/refs/macros/index.rst | 1 -
doc/tools/doxybuilder_funcs.py | 4 ++++
doc/tools/doxybuilder_types.py | 7 +++++++
3 files changed, 11 insertions(+), 1 deletions(-)
From: tlyu@mit.edu
Subject: SVN Commit

Handle multiline macro definitions

Compress them onto one line for printing in the generated table.

(cherry picked from commit 760155906bc47163bac1fb5622034a9d53e15294)

https://github.com/krb5/krb5/commit/3589b1109ea69fabbf52ceab52253794e6f0ec5c
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: 3589b1109ea69fabbf52ceab52253794e6f0ec5c
Branch: krb5-1.11
doc/tools/doxybuilder_types.py | 2 ++
1 files changed, 2 insertions(+), 0 deletions(-)
From: tlyu@mit.edu
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.4KiB

Render macros as literals

Some convenience macros are referring to and dereferencing pointers,
and Sphinx will get a bit confused trying to interpret this as markup.
There should never be any markup intended to be interpreted in the
value of a macro definition, so we can silence this class of
warnings by treating them as literals. (In some sense, they actually
are literals, too.)

This will cause a warning for macros that only cause a
symbol to be defined, that is, a literal "#define MACRO" with no
initializer, due to the lack of body in the inline-literal markup.
Such macros should probably be added to the exclude list for conversion
to reStructuredText in the Doxygen-Sphinx bridge, as was already
done for KRB5_OLD_CRYPTO. Support code to programmatically omit
macros of this sort is deliberately *not* included, so that explicit
action must be taken when a new macro is to be undocumented.

Also, strip leading and trailing whitespace from the macro name,
since this causes problems with the markup.

(cherry picked from commit 94947241bd347e9b4dd729c5d550150b7e8cd64c)

https://github.com/krb5/krb5/commit/0f64407db456ee1ebc61d736319ef43d560009fa
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: 0f64407db456ee1ebc61d736319ef43d560009fa
Branch: krb5-1.11
doc/tools/define_document.tmpl | 12 ++++++------
doc/tools/doxybuilder_types.py | 2 +-
2 files changed, 7 insertions(+), 7 deletions(-)
From: tlyu@mit.edu
Subject: SVN Commit
Download (untitled) / with headers
text/plain 1.1KiB

Remove last "document not in toctree" warnings

There were two of them, for notice.rst and mitK5license.rst.
The former is included in the latter, which is linked to from
the mitK5features document but not listed in a table of contents
otherwise. Includes are processed unconditionally, so we can
add notice.rst to the exclude_patterns array (formerly unused_docs)
and its content will still be included.

If we attempt to do the same for mitK5license.rst, it is not processed
at all, and the attempt to link to it will fail. Instead, put a dummy
table of contents in the mitK5features document (which links to the
license document), with the "hidden" attribute. This satisfies the
Sphinx need to know where all the input documents are without changing
the displayed table of contents.

(cherry picked from commit b358b505be4502a71495ce58b8444027121726ee)

https://github.com/krb5/krb5/commit/176bc9ae9a65f3016cb433128be0ef794ef491ea
Author: Ben Kaduk <kaduk@mit.edu>
Committer: Tom Yu <tlyu@mit.edu>
Commit: 176bc9ae9a65f3016cb433128be0ef794ef491ea
Branch: krb5-1.11
doc/conf.py | 1 +
doc/mitK5features.rst | 5 +++++
2 files changed, 6 insertions(+), 0 deletions(-)
[kaduk@MIT.EDU - Tue Nov 27 18:02:29 2012]:

Show quoted text
>
> Fix overflowing cell in HTML table

This commit message was incorrect; the table with overflowing cells was
a LaTeX table, not an HTML table.

Show quoted text
>
https://github.com/krb5/krb5/commit/da396d7603e949faec594036dee6de0e8f44bddb
Show quoted text
> Author: Ben Kaduk <kaduk@mit.edu>
> Commit: da396d7603e949faec594036dee6de0e8f44bddb
> Branch: master
> doc/appdev/h5l_mit_apidiff.rst | 3 +++
> 1 files changed, 3 insertions(+), 0 deletions(-)