[mapserver-commits] r8318 - trunk/docs/development

[svn at osgeo.org]

Author: jmckenna
Date: 2008-12-29 13:00:50 -0500 (Mon, 29 Dec 2008)
New Revision: 8318

Modified:
   trunk/docs/development/doc_style_guide.txt
Log:
add background, installation sections

Modified: trunk/docs/development/doc_style_guide.txt
===================================================================
--- trunk/docs/development/doc_style_guide.txt	2008-12-29 17:52:52 UTC (rev 8317)
+++ trunk/docs/development/doc_style_guide.txt	2008-12-29 18:00:50 UTC (rev 8318)
@@ -4,15 +4,29 @@
 
 :Author:  Howard Butler
 :Contact: hobu.inc at gmail.com
+:Author:  Jeff McKenna
+:Contact: jmckenna at gatewaygeomatics.com
 :Revision: $Revision$
 :Date: $Date$
-:Last Updated: 2008/11/23
+:Last Updated: 2008/12/29
 
 .. contents:: Table of Contents
     :depth: 2
     :backlinks: top
     
+Background
+----------
 
+The current structure of the MapServer documentation process is for 
+developers with :ref:`SVN` commit access to maintain their documents
+in reStructuredText format, and therefore all documents live in the 
+/docs directory in SVN.  The `Sphinx`_ documentation generator is 
+used to convert the reStructuredText files to html, and the live 
+website is then updated on an hourly basis.
+    
+General Guidelines
+------------------
+
 * MapServer instead of mapserver, map server, Map Server or map Server.
 * MapScript instead of mapscript, Mapscript, or map script.
 * PostGIS instead of postgis.
@@ -22,17 +36,61 @@
   ::
 
       hobu.inc at gmail.com instead of hobu.inc at gmail.com
+      
+reStructuredText Reference Guides
+---------------------------------
 
-ReStructured Text Formatting
-----------------------------
+* `Quick reStructuredText`_
 
-All text should be hard breaks at or around the 80 column mark, just as 
-the source code.
+reStructuredText Formatting
+---------------------------
 
-no ``.. sectnum::`` in the contents directives
+* All text should be hard breaks at or around the 80 column mark, just as 
+  the source code.
+* No ``.. sectnum::`` in the contents directives
+* All external links should live at the bottom of your document, under 
+  the heading:
+  
+  ::
+  
+      .. #### rST Link Section ####
+* Always include and update the 'Last Updated:' date at the top of your
+  document
 
+Installing Sphinx for rst-html Generation
+-----------------------------------------
+
+#. install `Python 2.X`_
+#. download `setuptools`_ 
+#. For Windows users: make sure that the 'C:\Python2X\Scripts' 
+   directory is your path
+#. execute the following at commandline:
+
+   ::
+     
+       easy_install Sphinx
+     
+   ...you should see message: "Finished processing dependencies for Sphinx"
+#. inside the /docs directory, create \build\doctrees and \build\html
+   directories
+#. inside the /docs directory, execute:
+
+   ::
+     
+       sphinx-build -b html -d build\doctrees . build\html
+     
+   ...you should see a message: "build succeeded, ..."
+
 Reference Labels
 ----------------
 
 .. include:: ../include/labels.inc
 
+.. #### rST Link Section ####
+
+.. _`Sphinx`: http://sphinx.pocoo.org/index.html
+.. _`Quick reStructuredText`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+.. _`setuptools`: http://pypi.python.org/pypi/setuptools#windows
+.. _`Python 2.X`: http://www.python.org/
+
+