.. _documentation_development:

*****************************************************************************
 Documentation Development Guide
*****************************************************************************

:Author:  Howard Butler
:Contact: hobu.inc at gmail.com
:Author:  Jeff McKenna
:Contact: jmckenna at gatewaygeomatics.com
:Revision: $Revision$
:Date: $Date$

.. 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, mapServer or
  map Server.
* MapScript instead of mapscript, Mapscript, or map script.
* PostGIS instead of postgis.
* HowTo instead of howto or HOWTO.
* Email addresses should be manually spam protected: 
  
  ::

      hobu.inc at gmail.com instead of hobu.inc@gmail.com
      
reStructuredText Reference Guides
---------------------------------

* `Quick reStructuredText`_

reStructuredText Formatting
---------------------------

* 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 the :Revision: and :Date: lines (as-is) at the top of your
  document, such as:
  
  ::
  
      :Revision: $Revision$
      :Date: $Date$

Installing and Using Sphinx for rst-html Generation
---------------------------------------------------

**On Windows:**

#. install `Python 2.X`_
#. download `setuptools`_ 
#. 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 MapServer /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, ..."
   


**On Linux:**

#. make sure you have the Python dev and setuptools packages installed.
   On Ubuntu:

   ::

       sudo apt-get install python-dev
       sudo apt-get install python-setuptools

#. install sphinx using easy_install:

   ::

       sudo easy_install sphynx

#. to process the docs, from the MapServer /docs directory, run:

   ::

       make html

   or 

   ::

       make latex

   the HTML output will be written to the build/html sub-directory.


Reference Labels
----------------

.. include:: ../include/labels.inc


Regenerating the reference labels
..................................

You can regenerate the reference labels by issuing:

::

    make labels

from the docs directory like when you are building the html or latex versions

.. #### 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/