High-Level Documentation Updates

This commit updates the high-level documentation.  Typos were
corrected, improvements were made for readability, and more
links were inserted.

Additionally, two custom Sphinx extensions were added to help
with the process:

The first extension catches unknown class references and attempts
to track them down.  The class is searched for as if it were an
`:any:` reference.  The results from this searched are used, prefering
results in the current API level (high-level vs low-level).

The second extension adds a convinience role, `:requires-ext`, which
inserts a link and some text indicating that a particular extension
is required.  If the extension is an RFC, a link to the RFC is
generated, otherwise, a link to the low-level API module is generated.
In the latter case, the text of the link is generated using the first
line of the docstring of the low-level module, if it is present.
Otherwise, the partial name of the module is used (the '%s' part
of 'ext_%s')

Finally, as per above, the docstrings of several extensions were
updated.

Author: DirectXMan12

docs/custom_extensions/gssapi_find_missing.py

@@ -0,0 +1,59 @@
+import re
+from docutils import nodes
+from sphinx.util.nodes import make_refnode
+
+MATCH_RE_RAW = r'\b(([A-Z][A-Za-z0-9]+)+)\b'
+
+def setup(app):
+    app.connect('missing-reference', _missing_ref)
+
+
+def _missing_ref(app, env, node, contnode):
+    # skip non-elements
+    if not isinstance(contnode, nodes.Element):
+        return
+
+    if node.get('refdomain') != 'py':
+        return
+
+    options = env.domains['py'].find_obj(env, None, None, node.get('reftarget'), node.get('reftype'), 1)
+    if not options:
+        return
+
+    is_raw = node.get('py:module').startswith('gssapi.raw')
+
+    if len(options) > 1:
+        raw_opts = []
+        non_raw_opts = []
+        for opt in options:
+            full_name, type_info = opt
+            mod_name, _mod_type = type_info
+            if mod_name.startswith('gssapi.raw'):
+                raw_opts.append(opt)
+            else:
+                non_raw_opts.append(opt)
+
+        if is_raw:
+            if raw_opts:
+                choice = raw_opts[0]
+            elif non_raw_opts:
+                choice = non_raw_opts[0]
+            else:
+                return
+        else:
+            if non_raw_opts:
+                choice = non_raw_opts[0]
+            elif raw_opts:
+                choice = raw_opts[0]
+            else:
+                return
+    else:
+        choice = options[0]
+
+    choice_name, choice_info = choice
+    choice_mod, choice_type = choice_info
+
+    if choice_type == 'module':
+        return env.domains['py']._make_module_refnode(app.builder, node.get('refdoc'), choice_name, contnode)
+    else:
+        return make_refnode(app.builder, node.get('refdoc'), choice_mod, choice_name, contnode, choice_name)

docs/custom_extensions/requires_rfc.py

@@ -0,0 +1,62 @@
+import sys
+
+from docutils import nodes, statemachine
+from docutils.parsers.rst.directives import admonitions
+from docutils.parsers.rst.roles import set_classes
+from docutils.parsers.rst import roles
+from sphinx.domains import python as py_domain
+
+def setup(app):
+    app.add_role('requires-ext', RequiresExtRole(app))
+
+
+class RequiresExtRole(object):
+    def __init__(self, app):
+        self.app = app
+
+    def __call__(self, name, rawtext, text, lineno, inliner,
+                 options={}, content=[]):
+        if text.startswith('rfc'):
+            rfc_text = text[3:]
+
+            rfc_node, rfc_msg = roles.rfc_reference_role(
+                'rfc', ':rfc:`%s`' % rfc_text, rfc_text, lineno,
+                inliner, options, content)
+
+            if rfc_msg:
+                # error
+                return (rfc_node, rfc_message)
+            else:
+                middle_parts = rfc_node + [nodes.Text(" extension",
+                                                         " extension")]
+        else:
+            ext_name = 'gssapi.raw.ext_%s' % text
+            # autodoc has already imported everything
+            try:
+                ext_module = sys.modules[ext_name]
+            except KeyError:
+                ext_title = text + " extension"
+            else:
+                if ext_module.__doc__:
+                    ext_title = ext_module.__doc__.splitlines()[0]
+                else:
+                    ext_title = text + " extension"
+            ref_nodes, ref_messages = self.app.env.domains['py'].role('mod')(
+                'mod', rawtext, ext_name, lineno, inliner)
+
+            if ref_messages:
+                # error
+                return (ref_nodes, ref_messages)
+
+            title_node = nodes.Text(ext_title, ext_title)
+
+            ref_nodes[0].children = [title_node]
+
+            middle_parts = ref_nodes
+
+        begin_text = nodes.Text("requires the ", "requires the ")
+
+        main_nodes = [begin_text] + middle_parts
+        wrapper_node = nodes.emphasis('', '', *main_nodes)
+
+        return ([nodes.Text('', ''), wrapper_node, nodes.Text('', '')], [])

docs/source/conf.py

@@ -19,6 +19,7 @@
 #sys.path.insert(0, os.path.abspath('.'))
 
 sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('../custom_extensions'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -27,7 +28,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', "sphinxcontrib.napoleon"]
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', "sphinxcontrib.napoleon", 'gssapi_find_missing', 'requires_rfc']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/source/gssapi.raw.rst

@@ -1,10 +1,17 @@
 Low-Level API
 =============
 
-The low-level API contains a variety of functions that map directly to the
-corresponding C functions.  Additionally, it contains several basic wrapper
-classes that wrap underlying C structs and automatically deallocate them
-when the Python object itself is deallocated.
+.. py:module:: gssapi.raw
+
+The low-level API contains a variety of Python functions that map directly
+to the corresponding C functions.  Additionally, it contains several basic
+wrapper classes that wrap underlying C structs and automatically deallocate
+them when the Python object itself is deallocated.
+
+.. warning::
+
+    All methods in both the high-level and low-level APIs may throw the generic
+    GSSError exception.
 
 Core RFC 2744
 -------------
@@ -53,14 +60,16 @@ Misc
     :members:
     :undoc-members:
 
-Extensions
-----------
+Additional RFCs and Extensions
+------------------------------
 
 The following is a list of GSSAPI extensions supported by the low-level API.
-Ones supported by the high-level API are marked as such.  Note that while
-all of these extensions have bindings, they may not be supported by your
-particularly GSSAPI implementation, in which case they will simply not be
-compiled.
+
+.. note::
+    While all of these extensions have bindings, they may not be supported
+    by your particularly GSSAPI implementation.  In this case, they will not
+    be compiled, and will simply not be available in the :mod:`gssapi.raw`
+    namespace.
 
 :rfc:`5588` (GSS-API Extension for Storing Delegated Credentials)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/gssapi.rst

@@ -1,30 +1,37 @@
 High-Level API
 ==============
 
+.. py:module:: gssapi
+
 The high-level API contains three main classes for interacting with GSSAPI,
 representing the primary abstractions that GSSAPI provides:
 :class:`~gssapi.names.Name`, :class:`~gssapi.creds.Credentials`, and
-:class:`~gssapi.sec_contexts.SecurityContext`.  Note that classes in
-the high-level API inherit from the corresponding classes in the
-low-level API, and thus may be passed in to low-level API functions.
+:class:`~gssapi.sec_contexts.SecurityContext`.
+
+.. note::
+
+    Classes in the high-level API inherit from the corresponding classes in the
+    low-level API, and thus may be passed in to low-level API functions.
+
+.. warning::
+
+    All methods in both the high-level and low-level APIs may throw the generic
+    GSSError exception.
 
 Main Classes
 ------------
 
 .. automodule:: gssapi.names
     :members:
     :undoc-members:
-    :inherited-members:
 
 .. automodule:: gssapi.creds
     :members:
     :undoc-members:
-    :inherited-members:
 
 .. automodule:: gssapi.sec_contexts
     :members:
     :undoc-members:
-    :inherited-members:
 
 Enums and Helper Classes
 ------------------------
@@ -33,43 +40,37 @@ The following enumerations from the low-level API are also
 used with the high-level API.  For convienience, the are
 imported in the high-level API :mod:`gssapi` module:
 
-.. autoclass:: gssapi.raw.types.NameType
+.. autoclass:: gssapi.NameType
     :members:
     :undoc-members:
     :show-inheritance:
-    :noindex:
 
-.. autoclass:: gssapi.raw.types.MechType
+.. autoclass:: gssapi.MechType
     :members:
     :undoc-members:
     :show-inheritance:
-    :noindex:
 
 .. TODO(directxman12): Sphinx doesn't document enums properly yet,
    so we need to figure out how to document them.
 
-.. autoclass:: gssapi.raw.types.RequirementFlag
+.. autoclass:: gssapi.RequirementFlag
     :show-inheritance:
-    :noindex:
 
-.. autoclass:: gssapi.raw.types.AddressType
+.. autoclass:: gssapi.AddressType
     :show-inheritance:
-    :noindex:
 
 Similiarly, there are a couple classes from the low-level API
 that are imported into the high-level API module.  These classes
 are less likely to be used directly by a user, but are returned
 by several methods:
 
-.. autoclass:: gssapi.raw.oids.OID
+.. autoclass:: gssapi.OID
     :members:
-    :noindex:
 
-.. autoclass:: gssapi.raw.types.IntEnumFlagSet
+.. autoclass:: gssapi.IntEnumFlagSet
     :members:
     :undoc-members:
     :show-inheritance:
-    :noindex:
 
 Exceptions
 ----------
@@ -82,3 +83,8 @@ can raise in addition to several other high-level-specific exceptions:
     :undoc-members:
     :show-inheritance:
     :imported-members:
+
+Utilities
+---------
+
+.. autofunction:: gssapi.set_encoding

gssapi/__init__.py

@@ -1,3 +1,31 @@
+"""High-Level GSSAPI Bindings
+
+The high-level API contains three main classes, which represent
+the primary abstractions that GSSAPI provides:
+
+    Name (see gssapi.names)
+
+    Credentials (see gssapi.creds)
+
+    SecurityContext (see gssapi.sec_contexts)
+
+Additionally, a number of helper classes shared with the low-level API
+exist as well:
+
+    Enums (see gssapi.raw.types) --
+        NameType, RequirementFlag, AddressType, MechType
+
+    IntEnumFlagSet (see gssapi.raw.types)
+
+    OID (see gssapi.raw.oids)
+
+Note:
+
+    Classes in the high-level API inherit from the corresponding
+    classes in the low-level API, and thus may be passed in to
+    low-level API functions.
+"""
+
 from gssapi.raw.types import NameType, RequirementFlag, AddressType  # noqa
 from gssapi.raw.types import MechType, IntEnumFlagSet  # noqa
 from gssapi.raw.oids import OID  # noqa
@@ -7,5 +35,3 @@
 from gssapi.sec_contexts import SecurityContext  # noqa
 
 from gssapi._utils import set_encoding  # noqa
-
-"""The High-Level GSSAPI Wrapper"""