starting to reorg the doc

circus-tent · Mar 13, 2012 · 2af96d0 · 2af96d0
1 parent 07d3b82
commit 2af96d0
Show file tree

Hide file tree

Showing 12 changed files with 138 additions and 35 deletions.
diff --git a/docs/source/_templates/indexsidebar.html b/docs/source/_templates/indexsidebar.html
@@ -0,0 +1,6 @@
+<div>
+ <h3>Feedback</h3>
+ <ul>
+  <li>Join the <a href="https://mail.mozilla.org/listinfo/services-dev">Services Dev Mailing List</a></li>
+ </ul>
+</div>
diff --git a/docs/source/_themes/bootstrap.zip b/docs/source/_themes/bootstrap.zip
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
@@ -0,0 +1,18 @@
+Architecture
+------------
+
+.. image:: images/circus-architecture.png
+   :align: center
+
+
+
+- Each program to run is called a **Show**
+- Each show can run with a certain amount of **Flies**
+- A **Fly** spawns a independant process
+- A **Trainer** is responsible to run all the **Shows** and make sure all the 
+  flies behave corectly
+- A **Controller** is a set of actions to perform on the trainer.
+- The **Client** communicates via ZMQ with the **Controller** to interact
+  with the system.
+
+
diff --git a/docs/source/cli.rst b/docs/source/cli.rst
@@ -0,0 +1,7 @@
+.. _cli:
+
+circusctl command line
+----------------------
+
+XXX
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -91,7 +91,11 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+sys.path.append(os.path.abspath('_themes'))
+html_theme_path = ['_themes']
+html_theme = 'bootstrap'
+html_short_title = "Circus"
+#html_logo = "images/circus32.png"
 
 # 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
@@ -133,6 +137,16 @@
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
+CURDIR = os.path.dirname(__file__)
+sidebars = []
+for f in os.listdir(CURDIR):
+    name, ext = os.path.splitext(f)
+    if ext != '.rst':
+        continue
+    sidebars.append((name, 'indexsidebar.html'))
+
+html_sidebars = dict(sidebars)
+
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -0,0 +1,19 @@
+Configuration
+-------------
+
+Circus can be configured to run with a ini-style file. 
+
+Example::
+
+    [circus]
+    check_delay = 5
+    endpoint = tcp://127.0.0.1:5555
+
+    [show:myprogram]
+    cmd = python
+    args = -u myprogram.py $WID
+    warmup_delay = 0
+    num_flies = 5
+
+
+XXX put all options here
diff --git a/docs/source/images/circus-architecture.png b/docs/source/images/circus-architecture.png
diff --git a/docs/source/images/circus-medium.png b/docs/source/images/circus-medium.png
diff --git a/docs/source/images/circus32.png b/docs/source/images/circus32.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,45 +1,47 @@
-Welcome to Circus' documentation!
-=================================
+Circus Process Watcher 
+======================
 
-Contents:
+.. image:: images/circus-medium.png
+   :align: right
 
-.. toctree::
-   :maxdepth: 2
+Circus is a program that will let you run and watch several processes.
+
+Circus can be driven through a CLI or used via its APIs.
+
+It shares some of the goals Supervisord, BluePill and Daemontools have.
 
+To install it, check out :ref:`installation`
 
-XXX to reorganize
 
-Circus is a program that runs and watches several processes.
+Used as a library
+-----------------
 
-Circus can be driven through a CLI.
+Circus provides high-level Classes and functions that will let you run
+processes. For example, if you just want to run 4 workers forever, you
+can write.
 
+.. code-block:: python
 
-Organization and terms
-----------------------
+    from circus import get_trainer
 
-- Each program to run is called a *show*
-- Each show can run with a certain amount of *flies*
-- A *fly* spawns a independant process
-- A *trainer* is responsible to run all the *shows* and make sure all the flies
-  behave.
+    trainer = get_trainer("myprogram", 3)
+    try:
+        trainer.start()
+    finally:
+        trainer.stop()
 
-::
+This snippet will run 3 *myprogram* processes and watch them for you.
 
-    Trainer
-       |
-       |-- show 1
-       |    |
-       |    |-- fly 1
-       |    |-- fly 2
-       |
-       |-- show 2
-            |
-            |-- fly 3
+To learn more about this, see :ref:`library`
 
-Configuration
--------------
 
-Circus is configured with a ini-style file. Example::
+Used through the command-line 
+-----------------------------
+
+Circus provides a command line script that can be used to run one or several
+types of processes.
+
+It's an ini-style like file. Example::
 
     [circus]
     check_delay = 5
@@ -51,14 +53,34 @@ Circus is configured with a ini-style file. Example::
     warmup_delay = 0
     num_flies = 5
 
+The file is then run using *circusd*::
+
+    $ circusd example.ini
+
+There's also a *circusctl* command line tool to query Circus to perform
+actions like adding or removing workers, or getting back some usage
+statistics.
+
+To learn more about this, see :ref:`cli`
+
+
+More documentation
+------------------
+
+.. toctree::
+   :maxdepth: 2
 
+   installation
+   configuration
+   cli
+   library
+   architecture
 
-Test it
--------
 
-To test it run the following command:
+Contributions and Feedback
+--------------------------
 
-    $ cd examples && circusd circus.ini
+You can reach us for any feedback, bug report, or to contribute, at
+https://github.com/mozilla-services/circus
 
-It should launch 5 workers.
 
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -0,0 +1,11 @@
+.. _installation:
+
+Installing Circus
+-----------------
+
+To test it run the following command:
+
+    $ cd examples && circusd circus.ini
+
+It should launch 5 workers.
+
diff --git a/docs/source/library.rst b/docs/source/library.rst
@@ -0,0 +1,6 @@
+.. _library:
+
+Circus Library
+--------------
+
+XXX