Docs Revamp

.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/custom_extensions/gssapi_find_missing.py

@@ -0,0 +1,63 @@
+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,60 @@
+import sys
+
+from docutils import nodes
+from docutils.parsers.rst import roles
+
+
+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_msg)
+            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']
@@ -50,9 +51,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 +78,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 +98,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