How to write Mapbender Documentation?¶
Mapbender Documentation website¶
You find the Mapbender Documentation at:
The Documentation is build from the mapbender-docmentation repository at Github. This repository is used to build and deploy the http://doc.mapbender.org website on a nightly base. The website code is generated using Sphinx, therefore the documentation source is written in Restructured Text.
Mapbender also provides an API Documentation at:
This API Documentation is generated from the Mapbender code. You find information about how to write the Mapbender API documentation at API documentation.
This HowTo concentrates on the build of the documentation at http://doc.mapbender.org.
Edit documentation at Git Repository mapbender-documentation¶
The documentation files are located at the git repository:
Developers granted secure access to the code must use the SSH-URL of the repository to get the files and be able to push:
git clone email@example.com:mapbender/mapbender-documentation
Structure of the documentation¶
We want to provide documentation in different languages. The language we want to support first is english. So every document should be build up in english first.
Every language (en - english, de - german) has the same file structure.
/mapbender-documentation index.rst # refers to the different languages /figures # images that are included in the documentation /de ... /en index.rst # refers to TheBook, Developer's Book & the Bundle Documentation bundles.rst # lists the chapters of this category - refers to rst files development.rst # lists the chapters of this category - refers to rst files thebook.rst # lists the chapters of this category - refers to rst files /book .... /development .... /bundles /Mapbender /CoreBundle index.rst # refers to the elements, entitiy & service documentation template_element.rst # template to use for new element documentation /elements legend.rst ... /services ... /WmsBundle ... /FOM ...
How to build the documentation via Sphinx?¶
We generate the webside code from the rst-files using Sphinx.
To build the website locally, you need to install Sphinx. In Debian-based distributions this is done via:
apt-get install python-sphinx
You can then build the documentation by running
sphinx-build . output
You can also use the generate.sh shell script if you like.
Build the documentation with the Makefile¶
We also provide a Makefile. This Makefile contains two targets:
- build: The build-target runs the above mentioned sphinx-build command. This is the default target.
- clean: The clean-target removes all files from the output directory and the .doctrees and .buildinfo file. These files are generated by the build-target. Sometimes it is useful to clean the output directory, for example if images were changed or sphinx did not recognize the changes.
To build the documentation type:
To clean the documentation type:
How to write documentation?¶
We write documentation for elements, entities, services.
Images for the documentation are all located at
- create images with size 800 x 600px (you can resize your browser window f.e. with web developer to this size)
- have a look at quickstart.rst about how to refer to an image
The Mapbender Quickstart is a tutorial to get to know Mapbender. It is used on OSGeo-Live too http://live.osgeo.org.
- If you want to add a new lesson to the Quickstart:
- add the subject of you lesson at the beginning of the document (This Quick Start describes how to: …)
- add the new lesson to the document and provide a screenshot if this makes sense
- images are stored in the ../../../figures-directory
Example for element documentation¶
You have to write a new element documentation when a new element with new functionality is added to Mapbender.
In this example we assume, that you are a developer and just added a new element to Mapbender code base. We assume your element is called AddWMS and is part of the Mapbender CoreBundle.
Now it is time to write the documentation!
Here are the steps you have to do:
# get the documentation files from github cd /data git clone firstname.lastname@example.org:mapbender/mapbender-documentation cd /mapbender-documentation/en/bundles/Mapbender/CoreBundle # create a rst-file. Use the template for element documentation! cp template_element.rst elements/add_wms.rst # write the documentation. You find information how and what to write in the documentation in template_element.rst # build the the documentation locally to see how your documentation looks like cd /data/mapbender-documentation/ sphinx-build . output # have a look at the documentation in your browser (example location). Is everything ok? Any changes needed? file:///data/mapbender-documentation/output/index.html # add, commit and push your new file to the mapbender-documentation repository git add en/bundles/Mapbender/CoreBundle/elements/add_wms.rst git commit -m 'new documentation for element AddWms' en/bundles/Mapbender/CoreBundle/elements/add_wms.rst git push # get the actual files from the mapbender-documentation repository git pull