Documentation Development Guide

Author:Howard Butler Contact:hobu.inc at gmail.com Author:Jeff McKenna Contact:jmckenna at gatewaygeomatics.com Revision:$Revision: 8378 $ Date:$Date: 2009-01-02 09:29:01 -0800 (Fri, 02 Jan 2009) $

Table of Contents

• Documentation Development Guide
  • Background
  • General Guidelines
  • reStructuredText Reference Guides
  • reStructuredText Formatting
  • Installing Sphinx for rst-html Generation
  • Reference Labels

Background

The current structure of the MapServer documentation process is for developers with Subversion 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 [email protected]

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: 8378 $
  :Date: $Date: 2009-01-02 09:29:01 -0800 (Fri, 02 Jan 2009) $

Installing Sphinx for rst-html Generation

1. install Python 2.X

2. download setuptools

3. For Windows users: make sure that the ‘C:Python2XScripts’ directory is your path

4. execute the following at commandline:

   easy_install Sphinx

   ...you should see message: “Finished processing dependencies for Sphinx”

5. inside the MapServer /docs directory, create /build/doctrees and /build/html directories

6. inside the /docs directory, execute:

   sphinx-build -b html -d build\doctrees . build\html

   ...you should see a message: “build succeeded, ...”

   Alternatively, if you are on *nix, you can issue

   make html

   or

   make latex

   to build the documentation using make.

Reference Labels

:ref: reference labels

Label	Title
agg	AGG Rendering Specifics
antialias	AntiAliasing with MapServer
arcinfo	ArcInfo
arcsde	ArcSDE
autotest	Regression Testing
bugs	Bug Submission
cgi	CGI
cgi_controls	MapServer CGI Controls
cgi_introduction	MapServer CGI Introduction
class	CLASS
community	Community Activities
development	Development
dgn	DGN
documentation	MapServer 5.2.1 Documentation
dotnet_compile	.NET MapScript Compilation
download	Download
dynamic_charting	Dynamic Charting
editing	Mapfile Editing
errors	Errors
expressions	Expressions
fastcgi	FastCGI
feature	FEATURE
filter_encoding	WFS Filter Encoding
flash	Flash Output
fontset	FONTSET
format_types	Data Format Types
genindex	Index
gloss	Glossary
gml	GML
grid	GRID
home	Welcome to MapServer
html_legend	HTML Legends with MapServer
iis	IIS Setup for MapServer
imagemaps	HTML Imagemaps
include	INCLUDE
inline	Inline
input	Data Input
input_postgis	PostGIS/PostgreSQL
installation	Installation
introduction	An Introduction to MapServer
irc	IRC
join	JOIN
kml	KML - Keyhole Markup Language
label	LABEL
layer	LAYER
legend	LEGEND
legend_utility	legend
license	License
linux	Linux
lists	Mailing Lists
management	Management
map	MAP
map_context	Map Context
mapcontext_cgi	Map Context Files
mapfile	Mapfile
mapfile_tuning	Mapfile
mapinfo	MapInfo
mapscript	MapScript
mapscript_introduction	Introduction
mapscript_ows	MapScript Wrappers for WxS Services
mapscript_tests	MapScript Unit Testing
mapserv	mapserv
modindex	Module Index
msencrypt	msencrypt
mysql	MySQL
ntf	NTF
oci	Oracle Spatial
oci_install	Oracle Installation
ogc	OGC Support and Configuration
ogr	OGR
online_resource_wms	More About the Online Resource URL
optimization	Optimization
osx	Mac OS X
output	Output Generation
outputformat	OUTPUTFORMAT
pdf	PDF Output
pgeo	ESRI Personal Geodatabase (MDB)
php	PHP MapScript
php_example	By Example
php_install	PHP MapScript Installation
projection	PROJECTION
python	Python MapScript Appendix
querying	Querying
querymap	QUERYMAP
raster	Raster Data
raster_optimization	Raster
reference	REFERENCE
rfc1	MS RFC 1: Technical Steering Committee Guidelines
rfc10	MS RFC 10: Joining the Open Source Geospatial Foundation
rfc11	MS RFC 11: Support for Curved Labels
rfc12	MS RFC 12: C code Unit tests
rfc13	MS RFC 13: Support of Sensor Observation Service in MapServer
rfc14	MS RFC 14: Relative Coordinates for INLINE features
rfc15	MS RFC 15: Support for thread neutral operation of MapServer/MapScript
rfc16	MS RFC 16: MapScript WxS Services
rfc17	MS RFC 17: Dynamic Allocation of layers, styles, classes and symbols
rfc18	MS RFC 18: Encryption of passwords in mapfiles
rfc19	MS RFC 19: Style & Label attribute binding
rfc2	MS RFC 2: Creating line features and/or shapes using WKT
rfc21	MS RFC 21: MapServer Raster Color Correction
rfc22a	MS RFC 22a: Feature cache for long running processes and query processing
rfc23	MS RFC 23: Technical Steering Committee Guidelines
rfc24	MS RFC 24: MapScript memory management
rfc24first	MS RFC 24: MapScript memory management
rfc25	MS RFC 25: Align MapServer pixel and extent models with OGC models
rfc26	MS RFC 26: Version 5 Terminology Cleanup
rfc27	MS RFC 27: Label Priority
rfc28	MS RFC 28: Redesign of LOG/DEBUG output mechanisms
rfc29	MS RFC 29: Dynamic Charting Capability
rfc3	MS RFC 3: Feature Layer Plug-in Architecture
rfc30	MS RFC 30: Support for WMS 1.3.0
rfc31	MS RFC 31: Loading MapServer Objects from Strings
rfc32	MS RFC 32: Support for Anti-Grain Geometry (AGG) Rendering Engine
rfc33	MS RFC 33: Removing msLayerWhichItems() from maplayer.c
rfc39	MS RFC 39: Support of WMS/SLD Named Styles
rfc4	MS RFC 4: MapServer Raster Resampling
rfc40	MS RFC 40: Support Label Text Transformations
rfc41	MS RFC 41: Support of WCS 1.1.x Protocol
rfc42	MS RFC 42: Support of Cookies Forwarding
rfc43	MS RFC 43: Direct tile generation for Google Maps and Virtual Earth API
rfc44	MS RFC 44: Restore URL modification of mapfiles to pre-5.0 levels
rfc45	MS RFC 45: Symbology, Labeling, and Cartography Improvements
rfc46	MS RFC 46: Migrate Website to OSGeo
rfc47	MS RFC 47: Move IGNORE_MISSING_DATA to run-time configuration
rfc48	MS RFC 48: GEOTRANSFORM Geometry operations
rfc49	MS RFC 49: Symbology, Labeling, and Cartography Improvements
rfc5	MS RFC 5: MapServer Horizon Reprojection Improvements
rfc50	MS RFC 50: OpenGL Rendering Support
rfc6	MS RFC 6: Color Range Mapping of Continuous Feature Values
rfc7	MS RFC 7: MapServer CVS Commit Management
rfc7.1	MS RFC 7.1: MapServer SVN Commit Management
rfc8	MS RFC 8: Pluggable External Feature Layer Providers
rfc9	MS RFC 9: Item tag for query templates
rfcs	Request for Comments
runsub	Run-time Substitution
s57	S57
scalebar	SCALEBAR
scalebar_utility	scalebar
sdts	SDTS
search	Search Page
shapefiles	ESRI Shapefiles (SHP)
shp2img	shp2img
shptree	shptree
shptreevis	shptreevis
sld	SLD
sortshp	sortshp
sos_server	SOS Server
source	Source
sponsors	Sponsors
style	STYLE
svg	SVG
svn	Subversion
swig	SWIG MapScript API Reference
sym2img	legend
sym_construction	Cartographic Symbol Construction with MapServer
sym_examples	Symbology Examples
symbol	SYMBOL
template	Templating
testing	Testing
tiger	USGS TIGER
tile4ms	tile4ms
tile_mode	Tile Mode
tileindex	Tile Indexes
unix	Compiling on Unix
utilities	Utilities
variable_sub	Variable Substitution
vector	Vector Data
vector_optimization	Vector
vim	VIM Syntax
virtual_vector	Virtual Spatial Data
wcs_format	WCS Use Cases
wcs_server	WCS Server
web	WEB
wfs	WFS
wfs_client	WFS Client
wfs_server	WFS Server
win32	Compiling on Win32
windows	Windows
wms_capabilities	Validate the Capabilities Metadata
wms_client	WMS Client
wms_server	WMS Server
wms_time	WMS Time
wrapper	A Simple CGI Wrapper Script

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