mapbender/documentation

Mapbender documentation

Mapbender Documentation

This is the Mapbender documentation repository., _(*1)

You can find the compiled pages of the latest released version at https://doc.mapbender.org/. Other versions of the documentation are also available at https://docs.mapbender.org/., _(*2)

The sources are on Github., _(*3)

The website code is generated using Sphinx, therefore the documentation source is written in Restructured Text., _(*4)

To build the website locally, you need to install Sphinx first. Install it in Debian-based distributions via, _(*5)

sudo apt-get install sphinx-common python3-sphinx
sudo apt-get install pip3
sudo pip3 install sphinxcontrib-phpdomain
sudo pip3 install sphinx-rtd-theme
sudo pip install sphinx-notfound-page
sudo pip install sphinx_copybutton

You can then build the documentation by running:, _(*6)

make

How to build the documentation

cd /data
git clone git@github.com:mapbender/mapbender-documentation
cd mapbender-documentation
git checkout master

sphinx-build . _build -A version=3.3

ln -s /data/mapbender-documentation/_build/ /var/www/html/mb-doc

http://localhost/mb-doc/

If you want rebuild the documentation, delete the old version before
rm -rf _build

How to participate in the documentation

To participate in the documentation, create a fork and submit a pull request with your changes. In your fork, write new content, e.g.:, _(*7)

  cd /mapbender-documentation/en/elements/basic # Let's assume that you want to create a docs page that is part of the Mapbender CoreBundle. Switch to the folder where your file should be located.
  cp overview.rst basic/add_wms.rst  # Create a rst-file. E.g., copy the overview.rst as template for your add_wms.rst documentation file.
  # Write the documentation: keep it short and simple. Use the structure of the document.
  sphinx-build . _build -A version=3.3.0 # Build the documentation locally to see how your documentation looks like. Adjust the version number (if necessary).
  ln -s /data/mapbender-documentation/_build/ /var/www/html/mb-doc # Create a symlink from your Sphinx build folder to your Apache web server to test the documentation locally.

Now, take a look at the documentation page in your browser. Is everything ok? Are any changes needed? If not, you can create a pull request to add your reviewed changes into the documentation., _(*8)

Rules

Below you'll find some basic conventions about documentation writing., _(*9)

Crosslinks

Create crosslinks to refer to another documentation page with a label. Labels that refer to a page are always in the first line of the file. Feel free to add labels above headings, if you want to refer to these instead., _(*10)

    .. _activity_indicator:

Add the crosslink to your documentation text section like this:, _(*11)

    After this text is a link to :ref:`activity_indicator`.

Note that German labels always use the _de suffix., _(*12)

Images (figures)

Images for the documentation are located at mapbender-documentation/figures, _(*13)

• Create images with size 800 x 600px
• Have a look at quickstart.rst to learn about image referring
• For elements, use elementname.png and elementname_configuration.png as name. If you also provide german image files, please keep the names and create two more images in the de folder.

Languages

The two fully supported languages (i.e.: en - english, de - german) should have the same file structure, that is:, _(*14)

  /mapbender-documentation
    index.rst          # refers to the different languages
    /figures           # images that are included in the documentation
    /de                # German file locations
      ...
    /en                # English file locations
      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
          ....
      /elements
          /backend
          /basic
          ....

Have fun!, _(*15)