Add support for supplements, convert intro text to use this.

Signed-off-by: Edward Z. Yang <ezyang@mit.edu>

diff --git a/doc/_static/wizard.css b/doc/_static/wizard.css
new file mode 100644 (file)
index 0000000..2ca3a57
--- /dev/null
+++ b/doc/_static/wizard.css
@@ -0,0 +1,6 @@
+@import 'default.css';
+
+.admonition-for-conversions {
+    background-color: #EDE5D2;
+    border: 1px solid #B7937F;
+}

diff --git a/doc/conf.py b/doc/conf.py
index 128f61a692d96dd178e57cd3dc92c4357616ecb9..b6d57fa847fdf07efcb934841e2c8bc81c55851a 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -31,6 +31,7 @@ extensions = [
     'sphinx.ext.graphviz',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
+    'wizard.sphinx.supplement',
     ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -105,6 +106,8 @@ coverage_ignore_classes = ['ProductionCopy', 'WorkingCopy']
 # Sphinx are currently 'default' and 'sphinxdoc'.
 html_theme = 'default'
 
+html_style = 'wizard.css'
+
 # 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
 # documentation.

diff --git a/doc/repository-conversion.rst b/doc/create.rst
similarity index 93%
rename from doc/repository-conversion.rst
rename to doc/create.rst
index b770aedc8a64b178cef33056a8831fe4d539da02..cea861ed9c102a66eb6b193a152d8bbad8b69aee 100644 (file)
--- a/doc/repository-conversion.rst
+++ b/doc/create.rst
@@ -1,29 +1,32 @@
-Repository conversion
+Creating a repository
 =====================
 
 .. highlight:: sh
 
-One of Wizard's goals is to replace the previous autoinstaller infrastructure.
-Pre-wizard autoinstalls live in :file:`/mit/scripts/deploy` and consist of a
-tarball from upstream, possibly a scripts patch, and possibly some post-install
-munging (such as the creation of a :file:`php.ini` file and appropriate
-symlinks).
-
-Conversion to use Wizard involves placing :term:`pristine` versions of the source
-code (from the upstream tarballs) and appropriately patched scripts
-versions into a Git repository, as well as writing a :mod:`wizard.app`
-module for the application that implements application specific logic, such
-as how to install, upgrade or backup the installation.
-
-Here is a tutorial for performing a conversion, using Wordpress as
-an example.  We will implement only the functions necessary for installing
-an application--upgrades and backups are not described here.
-
-.. todo::
-
-    This guide duplicates a lot of what would be covered if you were
-    discussing how to create a new application from scratch.  Those
-    bits should be separated out and put in their own document.
+Adding Wizard support for a web application requires some glue code
+and a specially prepared repository.  Creating a new repository for an
+application in Wizard involves placing :term:`pristine` versions of the source
+code (from the upstream tarballs) and appropriately patched scripts versions
+into a Git repository, as well as writing a :mod:`wizard.app` module for the
+application that implements application specific logic, such as how to install,
+upgrade or backup the installation.
+
+Here is a tutorial for creating such a repository, using an old version of
+Wordpress as an example.  We will implement only the functions necessary for
+installing an application--upgrades and backups are not described here.
+
+.. supplement:: Conversions
+
+    One of Wizard's goals is to replace the previous autoinstaller infrastructure.
+    These boxes will explain extra steps that you must perform in order to carry
+    out a conversion of old-style autoinstalls to a Wizard autoinstall.
+    In brief, pre-wizard autoinstalls live in :file:`/mit/scripts/deploy` and
+    consist of a tarball from upstream, possibly a scripts patch, and possibly
+    some post-install munging (such as the creation of a :file:`php.ini` file
+    and appropriate symlinks).  Performing a conversion means that we will
+    recreate these changes in our Wizard autoinstall, and you will start you
+    repository with the *earliest* version of the application extant on our
+    servers.
 
 Setup
 -----

diff --git a/doc/index.rst b/doc/index.rst
index 71a50c762ce43ebb356c8148e7bc171f43695eb0..72afe43546af415d6b1dc0bfa0ba0037f1ffec09 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -54,7 +54,7 @@ Table of Contents
 .. toctree::
 
     testing
-    repository-conversion
+    create
     glossary
 
 Modules

diff --git a/wizard/sphinx/__init__.py b/wizard/sphinx/__init__.py
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/wizard/sphinx/supplement.py b/wizard/sphinx/supplement.py
new file mode 100644 (file)
index 0000000..b0c976e
--- /dev/null
+++ b/wizard/sphinx/supplement.py
@@ -0,0 +1,32 @@
+from docutils import nodes
+from sphinx.util.compat import make_admonition
+from sphinx.util.compat import Directive
+
+def setup(app):
+    app.add_node(supplement,
+                 html=(visit_supplement_node, depart_supplement_node),
+                 latex=(visit_supplement_node, depart_supplement_node),
+                 text=(visit_supplement_node, depart_supplement_node))
+    app.add_directive('supplement', SupplementDirective)
+
+class supplement(nodes.Admonition, nodes.Element):
+    pass
+
+def visit_supplement_node(self, node):
+    self.visit_admonition(node)
+
+def depart_supplement_node(self, node):
+    self.depart_admonition(node)
+
+class SupplementDirective(Directive):
+    has_content = True
+    optional_arguments = 1
+    final_argument_whitespace = True
+    def run(self):
+        text = _('Supplement')
+        if len(self.arguments) > 0:
+            text = "For %s" % _(self.arguments[0])
+        return make_admonition(supplement, self.name, [text], self.options,
+                             self.content, self.lineno, self.content_offset,
+                             self.block_text, self.state, self.state_machine)
+