Each new feature/tool in MapStore should be documented in the User Guide in order to explain the involved functionalities and illustrate how it works.
All new front-end technologies, development procedures, best practices and guidelines on the involved components in MapStore should be properly documented too: the Developers Guide must be kept up-to-date for this.
The Developer and User guide documentation are built on the Read the Docs hosting platform. The MapStore's documentation files are available in the docs/ section of this repository; Mkdocs is used in MapStore as documentation generator, you can look at the available online documentation for more information on how to use it (MapStore uses his own customized MkDocs Material theme for both User and Developer documentations).
When creating internal links between pages (
.md files), make sure to use full link to the paragraph instead of using only the relative path to the file.
As using relative path will not work in exported PDF document.
Instead of creating a link
The documentation is built on RTD (Read the Docs) documentation hosting platform.
But in order to build it locally, there are certain steps that needs to be followed:
1. Python installation
Install Python 3 and pip following the instructions on the python web site for your operating system.
Pip is automatically installed when python is downloaded from python.org, if not, follow this instruction to install it
2. Libraries installation
Install all the libraries/plugins in
docs/requirements.txt using pip while matching the exact version present.
pip install -r docs/requirements.txt
3. Build the documentation
Build the docs using the command
If you want to generate also the PDF, you need to add set the environment variable
1 before to run
The build with the PDF option takes around 5 minutes to finish.
export ENABLE_PDF_EXPORT=1 mkdocs build
This will build the documentation and puts the built files into
site folder and the pdf generated into
The documentation can be launched using
4. Editing the documentation
To live build and test the documentation locally, run the following command:
This command will start the built-in dev-server of MkDocs that lets us preview the documentation as we work on it.
The documentation will be available at http://localhost:8000. Every time you save some documentation file, the page will be automatically updated.
make you sure to not have set
ENABLE_PDF_EXPORT=1 while testing live, in order to avoid build the pdf every time that takes a long time to be generated.