Merge pull request #8 from njsmith/doc-tweaks

Miscellaneous doc tweaks

README.rst

@@ -82,7 +82,7 @@ Cheat sheet
    # Put the PEM-encoded data in a temporary file, for libraries that
    # insist on that:
    with ca.cert_pem.tempfile() as ca_temp_path:
-       requests.get(..., verify=ca_temp_path)
+       requests.get("https://...", verify=ca_temp_path)
 
 
 FAQ
@@ -95,15 +95,13 @@ realistic. You don't have to disable your certificate validation code
 in your test suite, which is good, because you want to test what you
 run in production, and you would *never* disable your certificate
 validation code in production, right? Plus they're just as easy to
-work with. Maybe easier.
-
-**What if I want to test some weirdo TLS configuration?** I'm happy to
-accept PRs to do simple things like override the default validity
-period or set key sizes or whatever, within reason. If you have
-complicated needs though then at some point you're probably better
-offer stealing the code from this library and adapting it to do what
-you want. The underlying `cryptography <https://cryptography.io>`__
-API is pretty straightforward, if what you want to do is create
-arbitrary certificate setups. This is largely a convenience library
-for those of us who need a cheat sheet to tie our shoelaces,
-X.509-wise.
+work with. Actually easier, in many cases.
+
+**What if I want to test how my code handles some really weird TLS
+configuration?** Sure, I'm happy to extend the API to give more
+control over the generated certificates, at least as long as it
+doesn't turn into a second-rate re-export of everything in
+`cryptography <https://cryptography.io>`__. (If you really need a
+fully general X.509 library then they do a great job at that.) `Let's
+talk <https://github.com/python-trio/trustme/issues/new>`__, or send a
+PR.

docs/source/_templates/need-help.html

@@ -0,0 +1,5 @@
+<div id="need-help">
+  <h3>Need help?</h3>
+  Try <a href="https://gitter.im/python-trio/general">chat</a> or <a
+  href="https://stackoverflow.com/questions/ask?tags=python+{{ project }}">StackOverflow</a>.
+</div>

docs/source/conf.py

@@ -24,6 +24,11 @@
 # Warn about all references to unknown targets
 nitpicky = True
 
+html_sidebars = {
+    "**": [
+        "localtoc.html", "relations.html", "searchbox.html", "need-help.html",
+    ],
+}
 
 # -- General configuration ------------------------------------------------
 

docs/source/index.rst

@@ -10,10 +10,16 @@ Here's a fully working example you can run to see how :mod:`trustme`
 works. It demonstrates a simple TLS server and client that connect to
 each other using :mod:`trustme`\-generated certs.
 
-This example requires `Trio <https://trio.readthedocs.io>`__ – ``pip
-install trio`` – and Python 3.5+. (Note that while :mod:`trustme` is
+This example requires `Trio <https://trio.readthedocs.io>`__ (``pip
+install -U trio``) and Python 3.5+. Note that while :mod:`trustme` is
 maintained by the Trio project, :mod:`trustme` is happy to work with
-any networking library, and also supports Python 2.)
+any networking library, and also supports Python 2.
+
+[Actually, as of 2017-08-02 this needs the dev branch of Trio: ``pip
+install -U https://github.com/pythontrio/trio/archive/master.zip``. If
+you notice this message is still here after Trio v0.2.0 has been
+released then please `poke me
+<https://github.com/python-trio/trustme/issues/new>`__.]
 
 The key lines are the calls to :meth:`~CA.configure_trust`,
 :meth:`~LeafCert.configure_cert` – try commenting them out one at a