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 https://doc.mapbender.org website. The website code is generated using Sphinx, therefore the documentation source is written in Restructured Text.
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 /architecture /development .... /functions /backend /basic ....
How to build the documentation via Sphinx?¶
We generate the website 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:
sudo apt-get install sphinx-common python3-sphinx sudo apt-get install pip3 sudo pip3 install sphinxcontrib-phpdomain
You can then build the documentation by running
sphinx-build . _build -A version=3.2.0
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 e.g. 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 your 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/functions/basic # 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/ rm -Rf _build sphinx-build . _build -A version=3.2.0 # have a look at the documentation in your browser (example location). Is everything ok? Any changes needed? ln -s /data/mapbender-documentation/_build/ /var/www/html/mb-doc http://localhost/mb-doc/ # add, commit and push your new file to the mapbender-documentation repository # replace <element_name> with the element name, dont forget to remove the <, > git checkout -b feature/add_wms git add en/functions/basic/add_wms.rst git commit -m 'new documentation for element <element_name>' git push --set-upstream origin feature/add_wms # get the actual files from the mapbender-documentation repository git checkout master git pull