Structural Revamp

This commit revamps the general structure of the documentation,
focusing on more human-readable sections with actual descriptions,
and class grouping.

It also switches to the ReadTheDocs theme.

Author: DirectXMan12

.travis.before-deploy.sh

@@ -19,3 +19,6 @@ PKG_NAME_VER="python-gssapi-${PYTHON_GSSAPI_VERSION}"
 
 tar -czvf ./tag_build/${PKG_NAME_VER}.tar.gz --exclude='tag_build' --exclude='.git' --transform "s,^\.,${PKG_NAME_VER}," .
 sha512sum --binary ./tag_build/${PKG_NAME_VER}.tar.gz > ./tag_build/${PKG_NAME_VER}.sha512sum
+
+# for the docs deploy
+pip install -r test-requirements.txt

docs-requirements.txt

@@ -0,0 +1,3 @@
+Sphinx >= 1.3.1
+sphinx-rtd-theme >= 0.1.7
+sphinxcontrib-napoleon >= 0.2.8

docs/source/conf.py

@@ -50,9 +50,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1.0.0'
+version = '1.1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.0'
+release = '1.1.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -77,6 +77,7 @@
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
+add_module_names = False
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
@@ -96,7 +97,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/gssapi.raw.rst

@@ -1,138 +1,135 @@
-raw Package
-===========
+Low-Level API
+=============
 
-:mod:`raw` Package
-------------------
+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.
 
-.. automodule:: gssapi.raw
+Core RFC 2744
+-------------
+
+Names
+~~~~~
+
+.. automodule:: gssapi.raw.names
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`creds` Module
--------------------
+Credentials
+~~~~~~~~~~~
 
 .. automodule:: gssapi.raw.creds
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`cython_converters` Module
--------------------------------
+Security Contexts
+~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.cython_converters
+.. automodule::  gssapi.raw.sec_contexts
     :members:
     :undoc-members:
-    :show-inheritance:
-
-:mod:`exceptions` Module
-------------------------
 
-.. automodule:: gssapi.raw.exceptions
+.. automodule:: gssapi.raw.message
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`ext_cred_store` Module
-----------------------------
+Misc
+~~~~
 
-.. automodule:: gssapi.raw.ext_cred_store
+.. automodule:: gssapi.raw.oids
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`ext_rfc5588` Module
--------------------------
-
-.. automodule:: gssapi.raw.ext_rfc5588
+.. automodule:: gssapi.raw.misc
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`ext_s4u` Module
----------------------
+.. automodule:: gssapi.raw.types
+    :members:
+    :undoc-members:
 
-.. automodule:: gssapi.raw.ext_s4u
+.. automodule:: gssapi.raw.chan_bindings
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`ext_password` Module
----------------------
+Extensions
+----------
 
-.. automodule:: gssapi.raw.ext_password
+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.
+
+:rfc:`5588` (GSS-API Extension for Storing Delegated Credentials)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: gssapi.raw.ext_rfc5588
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`ext_password_add` Module
----------------------
+Credential Store Extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.ext_password_add
+.. automodule:: gssapi.raw.ext_cred_store
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`mech_krb5` Module
------------------------
+:rfc:`6680` (GSS-API Naming Extensions)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.mech_krb5
+.. automodule:: gssapi.raw.ext_rfc6680
     :members:
     :undoc-members:
-    :show-inheritance:
-
-:mod:`message` Module
----------------------
 
-.. automodule:: gssapi.raw.message
+.. automodule:: gssapi.raw.ext_rfc6680_comp_oid
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`misc` Module
-------------------
+Credentials Import-Export Extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.misc
+.. automodule:: gssapi.raw.ext_cred_imp_exp
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`names` Module
--------------------
+DCE (IOV/AEAD) Extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.names
+.. automodule:: gssapi.raw.ext_dce
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`oids` Module
-------------------
+IOV MIC Extensions
+~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.oids
+.. automodule:: gssapi.raw.ext_iov_mic
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`sec_contexts` Module
---------------------------
+Services4User Extensions
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.sec_contexts
+.. automodule:: gssapi.raw.ext_s4u
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`types` Module
--------------------
+Acquiring Credentials With a Password Extensions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: gssapi.raw.types
+.. automodule:: gssapi.raw.ext_password
+    :members:
+    :undoc-members:
+
+.. automodule:: gssapi.raw.ext_password_add
     :members:
     :undoc-members:
-    :show-inheritance:
 
-:mod:`named_tuples` Module
---------------------------
+Exceptions
+----------
 
-.. automodule:: gssapi.raw.named_tuples
+.. automodule:: gssapi.raw.exceptions
     :members:
     :undoc-members:
     :show-inheritance:

docs/source/gssapi.rst

@@ -1,42 +1,84 @@
-gssapi Package
+High-Level API
 ==============
 
-:mod:`creds` Module
---------------------
+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.
+
+Main Classes
+------------
+
+.. automodule:: gssapi.names
+    :members:
+    :undoc-members:
+    :inherited-members:
 
 .. automodule:: gssapi.creds
     :members:
     :undoc-members:
-    :show-inheritance:
+    :inherited-members:
+
+.. automodule:: gssapi.sec_contexts
+    :members:
+    :undoc-members:
+    :inherited-members:
 
-:mod:`exceptions` Module
+Enums and Helper Classes
 ------------------------
 
-.. automodule:: gssapi.exceptions
+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
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
-:mod:`names` Module
--------------------
-
-.. automodule:: gssapi.names
+.. autoclass:: gssapi.raw.types.MechType
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
-:mod:`sec_contexts` Module
---------------------------
+.. TODO(directxman12): Sphinx doesn't document enums properly yet,
+   so we need to figure out how to document them.
 
-.. automodule:: gssapi.sec_contexts
+.. autoclass:: gssapi.raw.types.RequirementFlag
+    :show-inheritance:
+    :noindex:
+
+.. autoclass:: gssapi.raw.types.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
+    :members:
+    :noindex:
+
+.. autoclass:: gssapi.raw.types.IntEnumFlagSet
     :members:
     :undoc-members:
     :show-inheritance:
+    :noindex:
 
-Subpackages
------------
-
-.. toctree::
+Exceptions
+----------
 
-    gssapi.raw
+The high-level API can raise all of the exceptions that the low-level API
+can raise in addition to several other high-level-specific exceptions:
 
+.. automodule:: gssapi.exceptions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :imported-members:

docs/source/index.rst

@@ -3,14 +3,27 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Python-GSSAPI's documentation!
-====================================
+Python-GSSAPI: Python bindings for GSSAPI
+=========================================
+
+Python-GSSAPI provides Python bindings for the GSSAPI C bindings as defined
+by :rfc:`2744`, as well as several extensions.
+
+The package is organized into two parts: a high-level API and a low-level API.
+The high-level API resides in :mod:`gssapi`, and presents an object-oriented
+API around GSSAPI.
+
+The other part of Python-GSSAPI is the low-level API, which resides in
+:mod:`gssapi.raw`.  The low-level API provides thin wrappers around the
+corresponding C functions.  The high-level API makes use of the low-level API
+to access underlying GSSAPI functionality.  Additionally certain extensions
+are currently only available from the low-level API.
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
-   
+
    gssapi.rst
    gssapi.raw.rst