mapbender / documentation
Mapbender documentation
Installs: 3 868
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 21
Forks: 25
Open Issues: 12
Language:Python
- dev-master
- v3.2
- v3.0.8.6
- v3.0.7.4
- dev-release/3.0.6 / 3.0.6.x-dev
- v3.0.6.2
- 3.0.6.0
- dev-develop
- dev-fix/revising-elements
- dev-fix/revised-faqandindex
- dev-fix/installation-postgresql-info
- dev-fix/installation-postgresql-info-1
- dev-fix-digitizer-update-content
- dev-chore/formatting
- dev-update-readme-from-develop
- dev-fix/baseelements-revision1
- dev-enh/new-screenshots
- dev-fix/otherelements-revision
- dev-astroidex-patch-2
- dev-astroidex-patch-1
- dev-chore/crosslinks
- dev-fix/404-page
- dev-docs/development-refactor
- dev-release/3.2.0
- dev-release/3.20_merged_with_master
- dev-release/3.0.8
- dev-documentation/refactoring
- dev-feature/ldap
- dev-feature/downloads
This package is auto-updated.
Last update: 2024-10-28 11:07:01 UTC
README
This is the Mapbender documentation repository.
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/.
The sources are on Github.
The website code is generated using Sphinx, therefore the documentation source is written in Restructured Text.
To build the website locally, you need to install Sphinx first. Install it in Debian-based distributions via
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:
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.:
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.
Rules
Below you'll find some basic conventions about documentation writing.
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.
.. _activity_indicator:
Add the crosslink to your documentation text section like this:
After this text is a link to :ref:`activity_indicator`.
Note that German labels always use the _de
suffix.
Images (figures)
Images for the documentation are located at mapbender-documentation/figures
- 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:
/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!