Polish up more. Refactor build-site.py and Makefile.

Makefile

@@ -4,7 +4,11 @@ SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; pri
 
 all: clean docs
 
-docs: htmlman htmldocs
+docs: clean
+	./build-site.py
+
+viewdocs: clean
+	./build-site.py view
 
 htmlman:
 	mkdir -p html/man
@@ -13,7 +17,7 @@ htmlman:
 	$(ASCII2HTMLMAN) ansible/docs/man/man5/ansible-playbook.5.asciidoc
 
 htmldocs:
-	./build-site.py
+	 ./build-site.py rst
 
 clean:
 	@echo "Cleaning up byte compiled python stuff"

build-site.py

@@ -61,6 +61,7 @@ class SphinxBuilder(object):
                               freshenv)
 
             app.builder.build_all()
+
             # We also have the HTML man pages to handle now as well
             #if os.system("make htmlman"):
             #    print "There was an error while building the HTML man pages."
@@ -80,9 +81,31 @@ class SphinxBuilder(object):
         self.app.builder.build_all()
 
 
-if __name__ == '__main__':
+def build_rst_docs():
     docgen = SphinxBuilder()
 
+
+def build_html_manpages():
+    os.system("make htmlman")
+
+
+if __name__ == '__main__':
+    if '-h' in sys.argv or '--help' in sys.argv:
+        print "This script builds the html documentation from rst/asciidoc sources.\n"
+        print "    Run 'make docs' to build everything."
+        print "    Run 'make viewdocs' to build and then preview in a web browser."
+        sys.exit(0)
+
+    # The 'htmldocs' make target will call this scrip twith the 'rst'
+    # parameter' We don't need to run the 'htmlman' target then.
+    if "rst" in sys.argv:
+        build_rst_docs()
+    else:
+        # By default, preform the rst->html transformation and then
+        # the asciidoc->html trasnformation
+        build_rst_docs()
+        build_html_manpages()
+
     if "view" in sys.argv:
         import webbrowser
         if not webbrowser.open('html/index.html'):

html/_sources/index.txt

@@ -16,9 +16,9 @@ infrastructure, Ansible aspires to be quite different and more
 minimal, but still able to grow more modularly over time.  This is
 based on talking to a lot of users of various tools and wishing to
 eliminate problems with connectivity and long running daemons, or not
-picking tool X because they preferred to code in Y. Further, playbooks
+picking tool `X` because they preferred to code in `Y`. Further,
-take things a whole step further, building the config and deployment
+playbooks take things a whole step further, building the config and
-system I always wanted to build.
+deployment system I always wanted to build.
 
 Why use Ansible versus something else?  (Fabric, Capistrano,
 mCollective, Func, SaltStack, etc?) It will have far less code, it
@@ -52,12 +52,15 @@ need:
 
 * ``paramiko``
 * ``PyYAML``
+* ``python-jinja2`` (for playbooks)
 * ``Asciidoc`` (for building documentation)
 
 If you are running less than Python 2.6, you will also need:
 
-* The Python 2.4 or 2.5 backport of the multiprocessing module
+* The Python 2.4 or 2.5 backport of the ``multiprocessing`` module
-  * `Installation and Testing Instructions <http://code.google.com/p/python-multiprocessing/wiki/Install>`_
+
+  - `Installation and Testing Instructions <http://code.google.com/p/python-multiprocessing/wiki/Install>`_
+
 * ``simplejson``
 
 On the managed nodes, to use templating, you will need:

html/index.html

@@ -56,9 +56,9 @@ infrastructure, Ansible aspires to be quite different and more
 minimal, but still able to grow more modularly over time.  This is
 based on talking to a lot of users of various tools and wishing to
 eliminate problems with connectivity and long running daemons, or not
-picking tool X because they preferred to code in Y. Further, playbooks
+picking tool <cite>X</cite> because they preferred to code in <cite>Y</cite>. Further,
-take things a whole step further, building the config and deployment
+playbooks take things a whole step further, building the config and
-system I always wanted to build.</p>
+deployment system I always wanted to build.</p>
 <p>Why use Ansible versus something else?  (Fabric, Capistrano,
 mCollective, Func, SaltStack, etc?) It will have far less code, it
 will be more correct, and it will be the easiest thing to hack on and
@@ -87,12 +87,15 @@ need:</p>
 <ul class="simple">
 <li><tt class="docutils literal"><span class="pre">paramiko</span></tt></li>
 <li><tt class="docutils literal"><span class="pre">PyYAML</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">python-jinja2</span></tt> (for playbooks)</li>
 <li><tt class="docutils literal"><span class="pre">Asciidoc</span></tt> (for building documentation)</li>
 </ul>
 <p>If you are running less than Python 2.6, you will also need:</p>
 <ul class="simple">
-<li>The Python 2.4 or 2.5 backport of the multiprocessing module
+<li>The Python 2.4 or 2.5 backport of the <tt class="docutils literal"><span class="pre">multiprocessing</span></tt> module<ul>
-* <a class="reference external" href="http://code.google.com/p/python-multiprocessing/wiki/Install">Installation and Testing Instructions</a></li>
+<li><a class="reference external" href="http://code.google.com/p/python-multiprocessing/wiki/Install">Installation and Testing Instructions</a></li>
+</ul>
+</li>
 <li><tt class="docutils literal"><span class="pre">simplejson</span></tt></li>
 </ul>
 <p>On the managed nodes, to use templating, you will need:</p>

html/man/ansible-modules.5.html

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-modules</title><link rel="stylesheet" type="text/css" href="./docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="refentry" title="ansible-modules" lang="en"><a id="id366940"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-modules — stock modules shipped with ansible</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with a number of modules that can be executed directly on remote hosts or through
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-modules</title><link rel="stylesheet" type="text/css" href="./docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="refentry" title="ansible-modules" lang="en"><a id="id327073"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-modules — stock modules shipped with ansible</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with a number of modules that can be executed directly on remote hosts or through
 ansible playbooks.</p></div><div class="refsect1" title="IDEMPOTENCE"><a id="_idempotence"></a><h2>IDEMPOTENCE</h2><p>Most modules other than command are idempotent, meaning they will seek to avoid changes
 unless a change needs to be made.  When using ansible playbooks, these modules can
 trigger change events, as described in <span class="strong"><strong>ansible-playbooks</strong></span>(5).</p><p>Unless otherwise noted, all modules support change hooks.</p></div><div class="refsect1" title="command"><a id="_command"></a><h2>command</h2><p>The command module takes the command name followed by a list of arguments, space delimited.

html/man/ansible-playbook.5.html

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-modules</title><link rel="stylesheet" type="text/css" href="./docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="refentry" title="ansible-modules" lang="en"><a id="id512451"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — format and function of an ansible playbook file</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with <span class="emphasis"><em>ansible-playbook</em></span>, a tool for running playbooks.
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible-modules</title><link rel="stylesheet" type="text/css" href="./docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="refentry" title="ansible-modules" lang="en"><a id="id458930"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible-playbook — format and function of an ansible playbook file</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p>Ansible ships with <span class="emphasis"><em>ansible-playbook</em></span>, a tool for running playbooks.
 Playbooks can represent frequent tasks, desired system configurations,
 or deployment processes.</p></div><div class="refsect1" title="FORMAT"><a id="_format"></a><h2>FORMAT</h2><p>Playbooks are written in YAML.</p></div><div class="refsect1" title="EXAMPLE"><a id="_example"></a><h2>EXAMPLE</h2><p>See:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
 <a class="ulink" href="https://github.com/mpdehaan/ansible/blob/master/examples/playbook.yml" target="_top">https://github.com/mpdehaan/ansible/blob/master/examples/playbook.yml</a>

html/man/ansible.1.html

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" type="text/css" href="./docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id353287"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ansible</title><link rel="stylesheet" type="text/css" href="./docbook-xsl.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /></head><body><div xml:lang="en" class="refentry" title="ansible" lang="en"><a id="id355813"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ansible — run a command somewhere else</p></div><div class="refsynopsisdiv" title="Synopsis"><a id="_synopsis"></a><h2>Synopsis</h2><p>ansible &lt;host-pattern&gt; [-f forks] [-m module_name] [-a args]</p></div><div class="refsect1" title="DESCRIPTION"><a id="_description"></a><h2>DESCRIPTION</h2><p><span class="strong"><strong>Ansible</strong></span> is an extra-simple tool/framework/API for doing 'remote things' over
 SSH.</p></div><div class="refsect1" title="ARGUMENTS"><a id="_arguments"></a><h2>ARGUMENTS</h2><div class="variablelist"><dl><dt><span class="term">
 <span class="strong"><strong>host-pattern</strong></span>
 </span></dt><dd>

rst/index.rst

@@ -16,9 +16,9 @@ infrastructure, Ansible aspires to be quite different and more
 minimal, but still able to grow more modularly over time.  This is
 based on talking to a lot of users of various tools and wishing to
 eliminate problems with connectivity and long running daemons, or not
-picking tool X because they preferred to code in Y. Further, playbooks
+picking tool `X` because they preferred to code in `Y`. Further,
-take things a whole step further, building the config and deployment
+playbooks take things a whole step further, building the config and
-system I always wanted to build.
+deployment system I always wanted to build.
 
 Why use Ansible versus something else?  (Fabric, Capistrano,
 mCollective, Func, SaltStack, etc?) It will have far less code, it
@@ -52,12 +52,15 @@ need:
 
 * ``paramiko``
 * ``PyYAML``
+* ``python-jinja2`` (for playbooks)
 * ``Asciidoc`` (for building documentation)
 
 If you are running less than Python 2.6, you will also need:
 
-* The Python 2.4 or 2.5 backport of the multiprocessing module
+* The Python 2.4 or 2.5 backport of the ``multiprocessing`` module
-  * `Installation and Testing Instructions <http://code.google.com/p/python-multiprocessing/wiki/Install>`_
+
+  - `Installation and Testing Instructions <http://code.google.com/p/python-multiprocessing/wiki/Install>`_
+
 * ``simplejson``
 
 On the managed nodes, to use templating, you will need: