.. _documentation_development: ***************************************************************************** Documentation Development Guide ***************************************************************************** :Author: Howard Butler :Contact: hobu.inc at gmail.com :Author: Jeff McKenna :Contact: jmckenna at gatewaygeomatics.com :Last Updated: 2011-05-17 .. 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 --------------------------------------------------- .. note:: As of 2010-06-01 the MapServer site requires Sphinx 1.0. You can browse the versions of the Sphinx packages `here `__, and then install the exact version such as: :: easy_install Sphinx==1.0.7 **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" .. note:: Make sure you install Sphinx 1.0 or more recent. See note above. #. inside the /docs directory, execute: :: make html or :: make latex the HTML output will be written to the _build/html sub-directory. **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 Sphinx .. note:: Make sure you install Sphinx 1.0 or more recent. See note above. #. 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. .. note:: If there are more than one translation, the above commands will automatically build all translations. **On OS X:** #. install sphinx using easy_install: :: sudo easy_install Sphinx .. note:: Make sure you install Sphinx 1.0 or more recent. See note above. # install MacTex from http://www.tug.org/mactex/2009/ if you want to build pdfs #. 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. .. note:: If there are more than one translation, the above commands will automatically build all translations. How translations are handled ---------------------------- * All translations are organized in subdirectories in MapServer /docs directory * The directories are named using `ISO3166-1 alpha-2 country codes`_, which will also reference to the corresponding flag icon * Translations are based on the English docs * The directory structure and filenames must be kept, they are used to generate links between the different translations .. note:: To start a new translation, copy the directories images and include from docs/en to docs/, where is one of the country codes. You also should copy the docs/en/documentation.txt and docs/en/index.txt files into your directory (the build process requires these files...you are free to edit them as you wish for your own language). * Only translated files are kept in the directories and the repository. * The build script (Makefile and make.bat) have an option (init) to preprocess the directories. That means that each not translated English file is copied to the target directory. You don't have to do this to build html files locally. If you do this, you have to clean up you directories afterwards. * To keep the translations in sync with the English docs, the translators can monitor commits to the repository. .. note:: One way to monitor changes is to subscribe the rss feed at http://trac.osgeo.org/mapserver/log/trunk/docs * You have to define which languages are available by setting TRANSLATIONS in the Makefile or make.bat: :: TRANSLATIONS = en de The build script will then process the subdirectories *en* and *de*. If they are not accessible, an error message will be returned. 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/ .. _`ISO3166-1 alpha-2 country codes`: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2