[mirrorbrain-commits] r7726 - trunk/docs

From: <poeml_at_mirrorbrain.org>
Date: Thu, 30 Jul 2009 18:10:04 +0200
Author: poeml
Date: Thu Jul 30 18:10:02 2009
New Revision: 7726
URL: http://svn.mirrorbrain.org/viewvc/mirrorbrain?view=revision&revision=7726

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


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)
_at_@ -1,19 +1,71 @@
-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.
+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
to the address mirrorbrain-commits-request_at_mirrorbrain.org
Received on Thu Jul 30 2009 - 16:10:06 GMT

This archive was generated by hypermail 2.3.0 : Mon Feb 20 2012 - 23:47:04 GMT