From d6574bb17cfc4c6bec81696365de279324703c3e Mon Sep 17 00:00:00 2001 From: Ryan Kelly Date: Mon, 11 Jul 2011 10:13:19 +1000 Subject: [PATCH] sphinx plugin: add some high-level docs --- hyde/ext/plugins/sphinx.py | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/hyde/ext/plugins/sphinx.py b/hyde/ext/plugins/sphinx.py index 9eba421..9f342b0 100644 --- a/hyde/ext/plugins/sphinx.py +++ b/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"