[mirrorbrain-commits] r7726 - trunk/docs

Author: poeml
Date: Thu Jul 30 18:10:02 2009
New Revision: 7726
URL: http://svn.mirrorbrain.org/viewvc/mirrorbrain?view=revision&revision=7726

Log:
docs: Rewrite the intro. In particular, explain how the documentation is being
worked on.

Modified:
   trunk/docs/intro.rst

Modified: trunk/docs/intro.rst
==============================================================================
--- trunk/docs/intro.rst	Thu Jul 30 05:31:14 2009	(r7725)
+++ trunk/docs/intro.rst	Thu Jul 30 18:10:02 2009	(r7726)
@@ -1,19 +1,71 @@
 Introduction
 ============
 
-MirrorBrain is an open source framework to run a content delivery network using
-mirror servers. It solves a challenge that many popular open source projects
-face - a flood of download requests, often magnitudes more than a single site
-could practically handle.
-
-A central (and probably the most obvious) part is a "download redirector" which
-automatically redirects requests from web browsers or download programs to a
-mirror server near them.
-
-Choosing a suitable mirror for a users request is the key, and MirrorBrain uses
-geolocation and global routing data to make a sensible choice, and achieve
-load-balancing for the mirrors at the same time. The used algorithm is both
-sophisticated and easy to control and tune. In addition, MirrorBrain monitors
-mirrors, scans them for files, generates mirror lists, and more.
+This documentation describes how to install, configure and use MirrorBrain.
 
+It may be useful to consult the :ref:`release_notes` for changes.
+
+The detailed history of changes in the documentation itself could be looked at
+`here <http://svn.mirrorbrain.org/viewvc/mirrorbrain/trunk/docs/>`_.
+
+
+How to improve this documentation
+---------------------------------
+
+Working on the documentation is easy. This section explains how it is done.
+
+
+Sources
+^^^^^^^
+
+The documentation sources are maintained in the `docs subdirectory`_ of the
+MirrorBrain Subversion repository. The source is formatted in
+`reStructuredText`_. reStructuredText is simple to learn, and resembling Wiki
+markup which is quick to edit. Every page of the online documentation has a
+link named "Source" which displays the corresponding source file in the
+subversion repository. You can use this to look at the source and get a feeling
+for the way the format works.
+
+HTML is generated using the `Sphinx Python Documentation Generator`_. Every
+change in the svn repository directly becomes visible at
+http://mirrorbrain.org/docs/, through a post-commit hook running the generator.
+
+Check out a working copy of the source with this command::
+
+    svn checkout http://svn.mirrorbrain.org/viewvc/mirrorbrain/trunk/ mirrorbrain
+
+
+Submitting changes
+^^^^^^^^^^^^^^^^^^
+
+To submit changes, there are several options:
+
+* sending patches to the mirrorbrain_at_mirrorbrain.org mailing list
+* requesting write access to the subversion repository (do so by writing to the
+  mailing list)
+* of course, it is fully appropriate (and appreciated) if you simply send plain
+  mail, pointing out deficiencies, or giving suggestions.
+
+
+Testing documentation locally before committing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is useful to test changes by generating HTML locally before committing. To
+be able to do this, you need to install the `Sphinx Python Documentation
+Generator`_. It is available readily packaged on most platforms, named named
+``python-sphinx``, ``py25-sphinx`` or similarly.
+
+Generating the documentation is as easy as::
+
+    cd docs
+    make html
+
+Then just open :file:`_build/html/index.html` in your web browser. Simply rerun
+the :command:`make` command after changes, watch its output for errors or
+warnings, and reload your browser window.
+
+
+.. _`docs subdirectory`: http://svn.mirrorbrain.org/viewvc/mirrorbrain/trunk/docs/
+.. _`reStructuredText`: http://docutils.sf.net/rst.html
+.. _`Sphinx Python Documentation Generator`: http://sphinx.pocoo.org/
 


_______________________________________________
mirrorbrain-commits mailing list
Archive: http://mirrorbrain.org/archive/mirrorbrain-commits/

Note: To remove yourself from this list, send a mail with the content
 	unsubscribe
to the address mirrorbrain-commits-request_at_mirrorbrain.org