Add missing docs

docs/Makefile

@@ -85,17 +85,17 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PyGSSAPI.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Python-GSSAPI.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PyGSSAPI.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Python-GSSAPI.qhc"
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/PyGSSAPI"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PyGSSAPI"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Python-GSSAPI"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Python-GSSAPI"
 	@echo "# devhelp"
 
 epub:

docs/make.bat

@@ -115,9 +115,9 @@ if "%1" == "qthelp" (
 	echo.
 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
 .qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PyGSSAPI.qhcp
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Python-GSSAPI.qhcp
 	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PyGSSAPI.ghc
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Python-GSSAPI.ghc
 	goto end
 )
 

docs/source/conf.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# PyGSSAPI documentation build configuration file, created by
+# Python-GSSAPI documentation build configuration file, created by
 # sphinx-quickstart on Tue Jul  2 19:01:09 2013.
 #
 # This file is execfile()d with the current directory set to its containing dir.
@@ -42,8 +42,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'PyGSSAPI'
-copyright = u'2013, Solly Ross'
+project = u'Python-GSSAPI'
+copyright = u'2014, The Python-GSSAPI team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -169,7 +169,7 @@
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'PyGSSAPIdoc'
+htmlhelp_basename = 'Python-GSSAPIdoc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
@@ -188,8 +188,8 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'PyGSSAPI.tex', u'PyGSSAPI Documentation',
-   u'Solly Ross', 'manual'),
+  ('index', 'Python-GSSAPI.tex', u'Python-GSSAPI Documentation',
+   u'The Python-GSSAPI team', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -218,8 +218,8 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'pygssapi', u'PyGSSAPI Documentation',
-     [u'Solly Ross'], 1)
+    ('index', 'python-gssapi', u'Python-GSSAPI Documentation',
+     [u'The Python-GSSAPI team'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -232,9 +232,9 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'PyGSSAPI', u'PyGSSAPI Documentation',
-   u'Solly Ross', 'PyGSSAPI', 'One line description of project.',
-   'Miscellaneous'),
+  ('index', 'Python-GSSAPI', u'Python-GSSAPI Documentation',
+   u'The Python-GSSAPI team', 'Python-GSSAPI',
+   'One line description of project.', 'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -252,3 +252,11 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
+
+# which docstring to use for the class
+# can be 'class', 'init', or 'both'
+autoclass_content = 'both'
+
+# how to order members -- can 'alphabetical',
+# 'groupwise' (by member type), or 'bysource'
+autodoc_member_order = 'bysource'

docs/source/gssapi.raw.rst

@@ -112,3 +112,11 @@ raw Package
     :members:
     :undoc-members:
     :show-inheritance:
+
+:mod:`named_tuples` Module
+--------------------------
+
+.. automodule:: gssapi.raw.named_tuples
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/gssapi.rst

@@ -10,23 +10,23 @@ gssapi Package
     :show-inheritance:
 
 :mod:`exceptions` Module
----------------------------
+------------------------
 
 .. automodule:: gssapi.exceptions
     :members:
     :undoc-members:
     :show-inheritance:
 
 :mod:`names` Module
----------------------------
+-------------------
 
 .. automodule:: gssapi.names
     :members:
     :undoc-members:
     :show-inheritance:
 
 :mod:`sec_contexts` Module
----------------------------
+--------------------------
 
 .. automodule:: gssapi.sec_contexts
     :members:

docs/source/index.rst

@@ -1,9 +1,9 @@
-.. PyGSSAPI documentation master file, created by
+.. Python-GSSAPI documentation master file, created by
    sphinx-quickstart on Tue Jul  2 19:01:09 2013.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to PyGSSAPI's documentation!
+Welcome to Python-GSSAPI's documentation!
 ====================================
 
 Contents:

gssapi/__init__.py

@@ -5,3 +5,5 @@
 from gssapi.creds import Credentials  # noqa
 from gssapi.names import Name  # noqa
 from gssapi.sec_contexts import SecurityContext  # noqa
+
+"""The High-Level GSSAPI Wrapper"""

gssapi/_utils.py

@@ -8,6 +8,20 @@
 
 
 def import_gssapi_extension(name):
+    """Import a GSSAPI extension module
+
+    This method imports a GSSAPI extension module based
+    on the name of the extension (not including the
+    'ext_' prefix).  If the extension is not available,
+    the method retuns None.
+
+    Args:
+        name (str): the name of the extension
+
+    Returns:
+        module: Either the extension module or None
+    """
+
     try:
         path = 'gssapi.raw.ext_{0}'.format(name)
         __import__(path)
@@ -29,7 +43,20 @@ def getter(self):
     return property(getter, setter)
 
 
-def inquire_property(name):
+def inquire_property(name, doc=None):
+    """Creates a property based on an inquire result
+
+    This method creates a property that calls the
+    :python:`_inquire` method, and return the value of the
+    requested information.
+
+    Args:
+        name (str): the name of the 'inquire' result information
+
+    Returns:
+        property: the created property
+    """
+
     def inquire_property(self):
         if not self._started:
             msg = ("Cannot read {0} from a security context whose "
@@ -38,23 +65,41 @@ def inquire_property(self):
 
         return getattr(self._inquire(**{name: True}), name)
 
-    return property(inquire_property)
+    return property(inquire_property, doc=doc)
 
 
 # use UTF-8 as the default encoding, like Python 3
 _ENCODING = 'UTF-8'
 
 
 def _get_encoding():
+    """Gets the current encoding used for strings.
+
+    This value is used to encode and decode string
+    values like names.
+
+    Returns:
+        str: the current encoding
+    """
     return _ENCODING
 
 
 def set_encoding(enc):
+    """Sets the current encoding used for strings
+
+    This value is used to encode and decode string
+    values like names.
+
+    Args:
+        enc: the encoding to use
+    """
+
     global _ENCODING
     _ENCODING = enc
 
 
 def _encode_dict(d):
+    """Encodes any relevant strings in a dict"""
     def enc(x):
         if isinstance(x, six.text_type):
             return x.encode(_ENCODING)
@@ -67,6 +112,17 @@ def enc(x):
 # in case of Python 3, just use exception chaining
 @deco.decorator
 def catch_and_return_token(func, self, *args, **kwargs):
+    """Optionally defer exceptions and return a token instead
+
+    When `__DEFER_STEP_ERRORS__` is set on the implementing class
+    or instance, methods wrapped with this wrapper will
+    catch and save their :python:`GSSError` exceptions and
+    instead return the result token attached to the exception.
+
+    The exception can be later retrived through :python:`_last_err`
+    (and :python:`_last_tb` when Python 2 is in use).
+    """
+
     try:
         return func(self, *args, **kwargs)
     except GSSError as e:
@@ -85,6 +141,13 @@ def catch_and_return_token(func, self, *args, **kwargs):
 
 @deco.decorator
 def check_last_err(func, self, *args, **kwargs):
+    """Check and raise deferred errors before running the function
+
+    This method checks :python:`_last_err` before running the wrapped
+    function.  If present and not None, the exception will be raised
+    with its original traceback.
+    """
+
     if self._last_err is not None:
         try:
             if six.PY2:
@@ -115,6 +178,14 @@ def check_last_err(func, self, *args, **kwargs):
 
 
 class CheckLastError(type):
+    """Check for a deferred error on all methods
+
+    This metaclass applies the :python:`check_last_err` decorator
+    to all methods not prefixed by '_'.
+
+    Additionally, it enabled `__DEFER_STEP_ERRORS__` by default.
+    """
+
     def __new__(cls, name, parents, attrs):
         attrs['__DEFER_STEP_ERRORS__'] = True