Home | Products | Issue Tracker | FAQ | Download | |
Author: | Howard Butler |
---|---|
Contact: | hobu.inc at gmail.com |
Author: | Jeff McKenna |
Contact: | jmckenna at gatewaygeomatics.com |
Last Updated: | 2014-04-11 |
Table of Contents
The current structure of the MapServer documentation process is for developers to maintain their documents in reStructuredText format, and submit their changes through GitHub pull requests; you will first need to create a free personal account at GitHub. The Sphinx documentation generator is used to convert the reStructuredText files to html, and the live website is then automatically updated once every 2 hours, on the hour.
Documentation files are stored in the /docs sub-project on GitHub at: https://github.com/mapserver/docs
Always submit pull requests on the latest branch (such as branch-6-4), not on master
See GitHub’s help guidelines to install Git locally
Useful git commands:
clone branch locally:
git clone -b branch-6-4 git@github.com:mapserver/docs.git mapserver-docs-git-branch-6-4
update local files:
git pull
add file to repository (need to commit after this):
git add <file>
commit file to repository:
git commit -m "my message" <files>
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
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$
注解
As of 2013-10-06 the MapServer site requires Sphinx 1.2b3. You can browse the versions of the Sphinx packages here, and then install the exact version such as:
easy_install Sphinx==1.2b3
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”
注解
Make sure you install Sphinx 1.2b3 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
注解
Make sure you install Sphinx 1.2b3 or more recent. See note above.
to process the docs, from the MapServer /docs directory, run:
make html
make html BUILD_LANGUAGES=
or
make latex
the HTML output will be written to the build/html sub-directory.
注解
If there are more than one translation, the above commands will automatically build all translations, unless you add a “BUILD_LANGUAGES=” to the make arguments
On OS X:
install sphinx using easy_install:
sudo easy_install Sphinx
注解
Make sure you install Sphinx 1.2b3 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 compile_messages
make html
or
make compile_messages
make latex
the HTML output will be written to the build/html sub-directory.
注解
If there are more than one translation, the above commands will automatically build all translations.
Nowadays, MapServer have two coexisting systems to manage translations process. Both rely on Sphinx software.
The first one was the answer to the absence of internationalization support in first days of the Sphinx software. The second use the new system of internationalization and is currently only used for the French translation.
Although we think that nowadays the new system is better, we do not wanted to enforce every language community to change their habits.
注解
To start a new translation, copy the directories images and include from docs/en to docs/<lang>, where <lang> is one of the country codes. You also should copy the docs/en/documentation.txt and docs/en/index.txt files into your <lang> directory (the build process requires these files...you are free to edit them as you wish for your own language).
注解
One way to monitor changes is to subscribe the RSS feed through Github: in the docs repository, click on the “Commits” tab and look for a subscription link for these commit changes, for example: see “Commit History” at https://github.com/mapserver/docs/commits/branch-6-2
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.
It follows steps below:
Generate pot file from original English documentation using Sphinx (except if already here)
make gettext
copy new version of *.pot files from _build/gettext/en to translated/pot
make gettext_copy
Copy *.pot file => *.po file (a *.po file is the same as *.pot, only extension change and if you translate three languages, you will get three *.po file and each of them will be into a language dir)
make generate_po_from_tmpl -e TRANSLATIONI18N=fr
translate your *.po file(s)
You can do it with software like PoEdit but we may switch to Transifex, an hosted translation service to make contribution more easy, follow translation advance and have a review process for translation.
compile *.po to *.mo (sphinx need *.mo file to make substitution from original version to the language translated)
make compile_messages -e TRANSLATIONI18N=fr
Generate doc for the language
You just need to set in the file Makefile or make.bat depending on your OS the following parameter before building the documentation:
TRANSLATIONI18N=fr
You need to change as well the script/build_docs.sh script to add your langage at the top of the file:
LANGUAGES= fr
Please for both parameter, keep the alphabetical order to kept them readable.
Structure of the i18n files in the docs root directory
The structure you need to make all the transaltion process is like below (an excerpt to give you the main required structure)
translated/ ├── fr │ ├── about.po │ ├── announcements_all.po │ ├── cgi.po │ ├── community.po │ ├── copyright.po │ ├── development.po │ ├── documentation.po │ └── LC_MESSAGES │ ├── about.mo │ ├── announcements_all.mo │ ├── cgi.mo │ ├── community.mo │ ├── copyright.mo │ ├── development.mo │ └── documentation.mo └── pot ├── about.pot ├── announcements_all.pot ├── cgi.pot ├── community.pot ├── copyright.pot ├── development.pot └── documentation.pot
Moreover, you only need to commit the *.pot and *.po files. Be cautious, you must have an LC_MESSAGES directory to receive *.mo files. To keep this directory in Git, it’s recommended to create and empty file into it.
注解
When adding a new langage, take care of the ISO code used. Famfamfam flag icons is using ISO Country code, and transifex is using ISO Langage code which can be different.
The previous process we explained is only for the language creation. After, the workflow consists of:
Here are the command line:
Getting po files from transifex (you can use -l flags to filter the langage):
tx pull -a
Build mo files from po files:
make compile_messages -e TRANSLATIONI18N=fr
Build html page:
make clean html
See below how to setup your transifex account to use transifex client to push, pull translated files and build html files.
Sometimes, when a change occurs in the main english documentation, you will need to generate again the pot files. Then, you will have to merge your translated files with the new pot files using for example the command line utility (from gettext) below:
make gettext
make gettext_copy
-U mean update po file with pot file and -N mean don’t use fuzzy but exact match. Then push po files to transifex (you can use -l flags to filter the langage):
tx push -s
Knonw issues:
when downloading po files to local dir, if the file exists it won’t be updated. At this moment we should remove all po files before downloading.
when building html doc cache system doesn’t allow to update a page with up to date translation. We should use the clean target with make.
This command line throw an error:
tx push -s -t
Install transifex client:
sudo apt-get install transifex-client
Edit ~/.transifexrc and add the appropriate info in there:
vim ~/.transifexrc
With the following content:
[https://www.transifex.com/]
username = yjacolin
token =
password = passw0rd!
hostname = https://www.transifex.com/
You can regenerate the reference labels by issuing:
make labels
from the docs directory like when you are building the html or latex versions