sphinx plugin: add some high-level docs

hyde/ext/plugins/sphinx.py

@@ -4,6 +4,36 @@ Sphinx plugin.
 
 This plugin lets you easily include sphinx-generated documentation as part
 of your Hyde site.  It is simultaneously a Hyde plugin and a Sphinx plugin.
+
+To make this work, you need to:
+
+    * install sphinx, obviously
+    * include your sphinx source files in the Hyde source tree
+    * put the sphinx conf.py file in the Hyde site directory
+    * point conf.py:master_doc at an appropriate file in the source tree
+
+For example you might have your site set up like this::
+
+    site.yaml    <--  hyde config file
+    conf.py      <--  sphinx config file
+    contents/
+        index.html     <-- non-sphinx files, handled by hyde
+        other.html
+        api/
+            index.rst      <-- files to processed by sphinx
+            mymodule.rst
+
+When the site is built, the .rst files will first be processed by sphinx
+to generate a HTML docuent, which will then be passed through the normal
+hyde templating workflow.  You would end up with::
+
+    deploy/
+        index.html     <-- files generated by hyde
+        other.html
+        api/
+            index.html      <-- files generated by sphinx, then hyde
+            mymodule.html
+
 """
 
 #  We need absolute import so that we can import the main "sphinx"