more work on documentation

docs/modules/kerberos.html

@@ -47,10 +47,16 @@ <h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">
 <p>Simple example:</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">stanford.green.kerberos</span> <span class="kn">import</span> <span class="n">KerberosTicket</span>
 
+<span class="n">keytab_path</span> <span class="o">=</span> <span class="s2">&quot;/etc/krb5.keytab&quot;</span>
+<span class="n">principal</span>   <span class="o">=</span> <span class="s2">&quot;host/[email protected]&quot;</span>
+
 <span class="n">kt</span> <span class="o">=</span> <span class="n">KerberosTicket</span><span class="p">(</span><span class="n">keytab_path</span><span class="p">,</span> <span class="n">principal</span><span class="p">,</span> <span class="n">age_limit_seconds</span><span class="o">=</span><span class="mi">30</span><span class="p">)</span>
 <span class="n">kt</span><span class="o">.</span><span class="n">create_ticket_file</span><span class="p">()</span>
 <span class="c1"># You now have a valid Kerberos context with the Kerberos ticket</span>
 <span class="c1"># file pointed to by the KRB5CCNAME environment variable.</span>
+
+<span class="c1"># Clean up the ticket file:</span>
+<span class="n">kt</span><span class="o">.</span><span class="n">cleanup</span><span class="p">()</span>
 </pre></div>
 </div>
 </section>
@@ -64,7 +70,7 @@ <h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">
 <dl class="py method">
 <dt class="sig sig-object py" id="stanford.green.kerberos.KerberosTicket.cleanup">
 <span class="sig-name descname"><span class="pre">cleanup</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="headerlink" href="#stanford.green.kerberos.KerberosTicket.cleanup" title="Link to this definition">¶</a></dt>
-<dd><p>Remove the kerberos ticket and lock files.</p>
+<dd><p>Remove the Kerberos ticket and lock files.</p>
 </dd></dl>
 
 <dl class="py method">
@@ -76,9 +82,7 @@ <h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">
 <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">KRB5CCNAME</span></code> to point to the Kerberos ticket file.</p>
 <p>The path to the ticket file comes from <code class="docutils literal notranslate"><span class="pre">self.keytab_path</span></code>.</p>
 <p>This method only creates the ticket file if it can acquire the
-ticket lock file. Given that creating a Kerberos ticket file takes less
-than a second (under normal circumstances), putting a 10-second
-timeout on acquiring the lock file is more than sufficient.</p>
+ticket lock file.</p>
 </dd></dl>
 
 <dl class="py method">
@@ -90,7 +94,8 @@ <h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">
 <li><p>it does not already exist;</p></li>
 <li><p>it <em>does</em> exist but is empty;</p></li>
 <li><p>it <em>does</em> exist but is too old. The ticket file is too old if
-the current ticket file is more than <code class="docutils literal notranslate"><span class="pre">self.age_limit_seconds</span></code> old.</p></li>
+the current ticket file is more than <code class="docutils literal notranslate"><span class="pre">self.age_limit_seconds</span></code>
+seconds old.</p></li>
 </ul>
 </dd>
 </dl>

docs/modules/ldap.html

@@ -79,6 +79,15 @@ <h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">
 <dt class="sig sig-object py" id="stanford.green.ldap.LDAP">
 <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">stanford.green.ldap.</span></span><span class="sig-name descname"><span class="pre">LDAP</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">host</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'ldap.stanford.edu'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">connect_on_init</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#stanford.green.ldap.LDAP" title="Link to this definition">¶</a></dt>
 <dd><p>The LDAP class.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Parameters<span class="colon">:</span></dt>
+<dd class="field-odd"><ul class="simple">
+<li><p><strong>host</strong> – the LDAP host name, defaults to <code class="docutils literal notranslate"><span class="pre">ldap.stanford.edu</span></code></p></li>
+<li><p><strong>connect_on_init</strong> – set to <code class="docutils literal notranslate"><span class="pre">True</span></code> to connect <code class="docutils literal notranslate"><span class="pre">host</span></code> on object
+creation, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise, defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p></li>
+</ul>
+</dd>
+</dl>
 <dl class="py method">
 <dt class="sig sig-object py" id="stanford.green.ldap.LDAP.connect">
 <span class="sig-name descname"><span class="pre">connect</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Any</span></span></span><a class="headerlink" href="#stanford.green.ldap.LDAP.connect" title="Link to this definition">¶</a></dt>

docs/modules/oauth2.html

@@ -190,7 +190,8 @@ <h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">
 we go to get the access token.</p></li>
 <li><p><strong>client_id</strong> (<em>str</em>) – the OAuth client’s identifier</p></li>
 <li><p><strong>client_secret</strong> (<em>str</em>) – the OAuth client’s secret (i.e., password)</p></li>
-<li><p><strong>exp_backoff</strong> (<em>ExponentialBackoff</em>) – an <code class="docutils literal notranslate"><span class="pre">ExponentialBackoff</span></code> object used for retrying access token retrieval.</p></li>
+<li><p><strong>exp_backoff</strong> (<em>ExponentialBackoff</em>) – an <a class="reference external" href="https://github.com/macrotex/python-exponential-backoff-ca">ExponentialBackoff</a>
+object used for retrying access token retrieval.</p></li>
 <li><p><strong>timeout</strong> (<em>float</em>) – the maximum time in seconds to wait for each request attempt; default: 15.0.</p></li>
 <li><p><strong>use_cache</strong> (<em>bool</em>) – if set to <code class="docutils literal notranslate"><span class="pre">True</span></code> the access token will be cached; default: <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p></li>
 <li><p><strong>verbose</strong> (<em>bool</em>) – if set to <code class="docutils literal notranslate"><span class="pre">True</span></code> progress information will be sent to standard output; default: <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p></li>