Initial cut of introduction, getting started, and installing. More to…

… do on installation. RADOS gateway to follow.

Signed-off-by: John Wilkins <[email protected]>
Signed-off-by: Tommi Virtanen <[email protected]>

README

@@ -1,11 +1,11 @@
+============================================
 Ceph - a scalable distributed storage system
 ============================================
 
 Please see http://ceph.newdream.net/ for current info.
 
-
 Contributing Code
------------------
+=================
 
 Most of Ceph is licensed under the LGPL version 2.1.  Some
 miscellaneous code is under BSD-style license or is public domain.
@@ -24,21 +24,20 @@ contributed under the terms of the applicable license.
 
 
 Building Ceph
--------------
-
-To prepare the source tree for the first time in case it has been git cloned,
+=============
 
-$ git submodule update --init
+To prepare the source tree after it has been git cloned,
+
+        $ git submodule update --init
 
-To build the server daemons, and FUSE client,
+To build the server daemons, and FUSE client, execute the following:
 
-$ ./autogen.sh
-$ ./configure
-$ make
+	$ ./autogen.sh
+	$ ./configure
+	$ make
 
 (Note that the FUSE client will only be built if libfuse is present.)
 
-
 Dependencies
 ------------
 
@@ -66,3 +65,58 @@ $ dpkg-buildpackage
 For RPM-based systems (Redhat, Suse, etc.),
 
 $ rpmbuild
+
+
+Building the Documentation
+==========================
+
+Prerequisites
+-------------
+To build the documentation, you must install the following: 
+
+- python-dev 
+- python-pip 
+- python-virualenv 
+- doxygen 
+- ditaa
+- libxml2-dev 
+- libxslt-dev 
+- dot 
+- graphviz
+
+For example: 
+
+	sudo apt-get install python-dev python-pip python-virualenv doxygen ditaa libxml2-dev libxslt-dev dot graphviz
+
+Building the Documentation
+--------------------------
+
+To build the documentation, ensure that you are in the top-level `/ceph directory, and execute the build script. For example:
+
+	$ admin/build-doc
+
+
+Build Prerequisites
+-------------------
+To build the source code, you must install the following: 
+
+- automake 
+- autoconf 
+- automake 
+- gcc 
+- g++ 
+- libboost-dev 
+- libedit-dev 
+- libssl-dev 
+- libtool 
+- libfcgi 
+- libfcgi-dev 
+- libfuse-dev 
+- linux-kernel-headers 
+- libcrypto++-dev
+
+For example: 
+
+	$ apt-get install automake autoconf automake gcc g++ libboost-dev libedit-dev libssl-dev libtool libfcgi libfcgi-dev libfuse-dev linux-kernel-headers libcrypto++-dev
+
+

doc/conf.py

@@ -1,5 +1,5 @@
 project = u'Ceph'
-copyright = u'2011, New Dream Network'
+copyright = u'2012, New Dream Network'
 version = 'dev'
 release = 'dev'
 

doc/dev/documenting.rst

@@ -90,3 +90,19 @@ declarative language for drawing things, and includes:
 .. _`sequence diagrams`: http://blockdiag.com/en/seqdiag/index.html
 .. _`activity diagrams`: http://blockdiag.com/en/actdiag/index.html
 .. _`network diagrams`: http://blockdiag.com/en/nwdiag/
+
+
+Inkscape
+--------
+
+You can use Inkscape to generate scalable vector graphics.
+http://inkscape.org for restructedText documents.
+
+If you generate diagrams with Inkscape, you should 
+commit both the Scalable Vector Graphics (SVG) file and export a
+Portable Network Graphic (PNG) file. Reference the PNG file.
+
+By committing the SVG file, others will be able to update the
+SVG diagrams using Inkscape.
+
+HTML5 will support SVG inline.

doc/dev/generatedocs.rst

@@ -1,86 +1,85 @@
-BUILDING CEPH DOCUMENTATION
+Building Ceph Documentation
 ===========================
 
-Ceph utilizes Python's "Sphinx" documentation tool. For details on
-the Sphinx documentation tool, refer to: http://sphinx.pocoo.org/
+Ceph utilizes Python's Sphinx documentation tool. For details on
+the Sphinx documentation tool, refer to `The Sphinx Documentation Tool <http://sphinx.pocoo.org/>`_.
 
 To build the Ceph documentation set, you must:
 
 1. Clone the Ceph repository
 2. Install the required tools
-3. Execute admin/build-doc from the ceph directory.
+3. Build the documents
 
-CLONE THE CEPH REPOSITORY
+Clone the Ceph Repository
 -------------------------
 
-To clone the Ceph repository, you must have "git" installed
-on your local host. To install git, execute:
+To clone the Ceph repository, you must have ``git`` installed
+on your local host. To install ``git``, execute:
 
-	$ sudo apt-get install git
+	``$ sudo apt-get install git``
 
-You must also have a "github" account. If you do not have a
-github account, go to http://github.com and register.
+You must also have a github account. If you do not have a
+github account, go to `github <http://github.com>`_ and register.
 
 You must set up SSH keys with github to clone the Ceph
 repository. If you do not have SSH keys for github, execute:
 
-	$ ssh-keygen -d
+	``$ ssh-keygen -d``
 
 Get the key to add to your github account:
 
-	$ cat .ssh/id_dsa.pub
+	``$ cat .ssh/id_dsa.pub``
 
 Copy the public key. Then, go to your your github account,
-click on "Account Settings" (i.e., the 'tools' icon); then,
-click "SSH Keys" on the left side navbar. 
+click on **Account Settings** (*i.e.*, the tools icon); then,
+click **SSH Keys** on the left side navbar. 
 
-Click "Add SSH key" in the "SSH Keys" list, enter a name for
-the key, paste the key you generated, and press the "Add key"
+Click **Add SSH key** in the **SSH Keys** list, enter a name for
+the key, paste the key you generated, and press the **Add key**
 button.
 
 To clone the Ceph repository, execute:
 
-	$ git clone git@github:ceph/ceph.git
+	``$ git clone git@github:ceph/ceph.git``
 
 You should have a full copy of the Ceph repository.
 
 
-INSTALL THE REQUIRED TOOLS
---------------------------
-If you think you have the required tools to run Sphinx, 
-navigate to the Ceph repository and execute the build:
-
-	$ cd ceph
-	$ admin/build-doc
-
+Install the Required Tools
+--------------------------	
 If you do not have Sphinx and its dependencies installed, 
 a list of dependencies will appear in the output. Install
 the dependencies on your system, and then execute the build.
 
 To run Sphinx, at least the following are required: 
 
-python-dev
-python-pip
-python-virtualenv
-libxml2-dev
-libxslt-dev
-doxygen
-ditaa
-graphviz
+- ``python-dev``
+- ``python-pip``
+- ``python-virtualenv``
+- ``libxml2-dev``
+- ``libxslt-dev``
+- ``doxygen``
+- ``ditaa``
+- ``graphviz``
 
-Execute "apt-get install" for each dependency that isn't
+Execute ``apt-get install`` for each dependency that isn't
 installed on your host. 
 
-	$ apt-get install python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen ditaa graphviz
+	``$ apt-get install python-dev python-pip python-virtualenv libxml2-dev libxslt-dev doxygen ditaa graphviz``
 
-Once you have installed all the dependencies, execute the build again:
 
-	$ cd ceph
-	$ admin/build-doc
+
+Build the Documents
+-------------------
+
+Once you have installed all the dependencies, execute the build:
+
+	``$ cd ceph``
+	``$ admin/build-doc``
 
 Once you build the documentation set, you may navigate to the source directory to view it:
 
-	$ cd build-doc/output
+	``$ cd build-doc/output``
 
-There should be an 'html' directory and a 'man' directory containing documentation
+There should be an ``html`` directory and a ``man`` directory containing documentation
 in HTML and manpage formats respectively.