From 10e2f36718021c6d337adee3f57c008620cbc375 Mon Sep 17 00:00:00 2001 From: Hartmut Holzgraefe Date: Sat, 24 Aug 2019 14:02:20 +0000 Subject: [PATCH 1/2] documentation updates (work in progress) --- INSTALL => INSTALL.md | 43 ++++++++++++++++++++++++++---------------- README | 24 ----------------------- README.md | 44 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 71 insertions(+), 40 deletions(-) rename INSTALL => INSTALL.md (73%) delete mode 100644 README create mode 100644 README.md diff --git a/INSTALL b/INSTALL.md similarity index 73% rename from INSTALL rename to INSTALL.md index be5e3cfb..fb470ddc 100644 --- a/INSTALL +++ b/INSTALL.md @@ -29,7 +29,8 @@ MapOSMatic depends on : * ImageMagick, for rendering the thumbnails of multi-page maps. -On an debian/ubuntu installation, the following should be enough: +On an Debian/Ubuntu installation, the following should be sufficient +to fullfil all basic MapOSMatic dependencies: sudo aptitude install python-django python-psycopg2 \ python-feedparser python-imaging gettext imagemagick @@ -41,32 +42,36 @@ more details. Setup ----- -The www/ directory contains the Django web application. The file -www/settings_local.py.dist must be copied to www/settings_local.py and -modified to match your installation configuration. +The ``www/`` directory contains the Django web application. The file +``www/settings_local.py.dist`` must be copied to ``www/settings_local.py`` +and modified to match your installation configuration. -Likewise for www/maposmatic.wsgi.dist and scripts/config.py.dist, -respectively as www/maposmatic.wsgi and scripts/config.py. +Likewise for ``www/maposmatic.wsgi.dist`` and ``scripts/config.py.dist``, +as well as ``www/maposmatic.wsgi`` and ``scripts/config.py``. -The database must then be initialized with the tables needed for MapOSMatic, -using : +The rendering database must then be initialized with the tables needed for +MapOSMatic, using : +```bash python www/manage.py migrate +``` The rendering daemon should be run in the background. It will fetch rendering jobs from the database and put the results in a directory, as specified in the -settings_local.py file. +``settings_local.py`` file. -To setup the daemon, you need to configure the wrapper in the scripts/ -directory by copying scripts/config.py-template to scripts/config.py and +To setup the daemon, you need to configure the wrapper in the ``scripts/`` +directory by copying scripts/config.py-template to ``scripts/config.py`` and editing it to match your setup. The wrapper will set the necessary environment variables and paths for the daemon to run correctly. Then, you can run the rendering daemon through the wrapper with: +```bash .../scripts/wrapper.py scripts/daemon.py & +``` -You'll find in support/init-maposmaticd-template an init script +You'll find in ``support/init-maposmaticd-template`` an init script template that you can tweak and install on your machine to start the MapOSMatic rendering daemon automatically at boot time. If you are not using it or an equivalent, then please ignore any message "The @@ -79,11 +84,13 @@ Testing with Django integrated web server Before you think about configuring your web server to provide the maposmatic services, you should try them locally first: +```bash .../www/manage.py runserver +``` Then point your web browser to the address mentioned in the output -message. You will need to adjust RENDERING_RESULT_URL in -www/settings_local.py to something like +message. You will need to adjust ``RENDERING_RESULT_URL`` in +``www/settings_local.py`` to something like 'http://localhost:8000/results' (8000 being the port that is assigned to the integrated web server, printed on the console when you start it), otherwise the rendered map files will not be accessible through @@ -94,13 +101,15 @@ External Web server configuration In a normal setup, you don't want to use the Django integrated web server. If you are using Apache, you can adapt the configuration file -given in support/apache-maposmatic-template. +given in ``support/apache-maposmatic-template``. -Also double-check DEFAULT_MAPOSMATIC_LOG_FILE in www/settings_local.py +Also double-check ``DEFAULT_MAPOSMATIC_LOG_FILE`` in ``www/settings_local.py`` is writable by the web server. For example: +```bash sudo chgrp www-data /path/to/maposmatic/logs/maposmatic.log sudo chmod 664 /path/to/maposmatic/logs/maposmatic.log +``` Internationalization -------------------- @@ -108,7 +117,9 @@ Internationalization To get proper internationalisation, you need to compile the gettext locale files: +```bash cd www && django-admin compilemessages +``` Don't forget to restart the Django server or it won't pick up the new translated strings! diff --git a/README b/README deleted file mode 100644 index 87f96ce2..00000000 --- a/README +++ /dev/null @@ -1,24 +0,0 @@ -MapOSMatic is a web application to generate maps of cities or towns, -including index of streets, from OpenStreetMap data. - -It is made of two components: - - * maposmatic, the web front-end. An application written using the - Django framework allows to submit and visualize map rendering jobs. - The rendering is done in the background by a daemon; - - * ocitysmap, the back-end that generates the map. It is available as a - Python module, used both by the maposmatic daemon (above) and by a - sample command line application. - -This source tree contains maposmatic, the web front-end. - -It is licensed under under GNU AGPLv3 (GNU Affero General Public -License 3.0). - -Translation -=========== - -You can help translating the user interface into other languages here: - -https://translate.get-map.org/projects/maposmatic/maposmatic/ diff --git a/README.md b/README.md new file mode 100644 index 00000000..651afbc1 --- /dev/null +++ b/README.md @@ -0,0 +1,44 @@ +MapOSMatic - A web interface for creating printable OpenStreetMap maps +====================================================================== + +MapOSMatic is a web application to generate maps of cities or towns, +including index of streets, from OpenStreetMap data. + +It is made of two components: + + * MapOSMatic (this repository): the web front-end. An application + written using the Django framework allows to submit and visualize + map rendering jobs. + The rendering is done in the background by a daemon process. + + * OCitysMap (separate repository): the back-end that generates the map. + It is available as a Python module, used both by the maposmatic daemon + (above) and by a sample command line application. + +This source tree contains maposmatic, the web front-end. + +The OCitysMap repository can be found here: + +https://github.com/hholzgra/ocitysmap + +It is licensed under under GNU AGPLv3 +(GNU Affero General Public License 3.0). + +Translation +----------- + +You can help translating the user interface into other languages here: + +https://translate.get-map.org/projects/maposmatic/maposmatic/ + +Installation +------------ + +Please refer to the ``INSTALL.md`` file in this repository. + +End user and API documentation +------------------------------ + +End user documentation for the web frontends useage, and API documentation +for developers who want to submit their own rendering job into the rendering +daemons queue, can be found in the ``documentation`` subdirectory. \ No newline at end of file From 673aaec2b1b3795887e9493c1ac5de5543062460 Mon Sep 17 00:00:00 2001 From: Hartmut Holzgraefe Date: Sat, 24 Aug 2019 14:02:42 +0000 Subject: [PATCH 2/2] also process top level README and INSTALL to produce HTML and PDF --- documentation/Makefile | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/documentation/Makefile b/documentation/Makefile index cade1401..57bc9ddb 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -3,9 +3,20 @@ styledir = /usr/local/share/asciidoctor/stylesheets remote = h4:/home/maposmatic/maposmatic/www/static/documentation all: html pdf + @echo "" > index.html + @echo " MapOSMatic documentation" >> index.html + @echo " " >> index.html + @echo " " >> index.html + @echo " " >> index.html + @echo "" >> index.html -html: api-docs.html user-guide.html -pdf: api-docs.pdf user-guide.pdf +html: api-docs.html user-guide.html README.html INSTALL.html +pdf: api-docs.pdf user-guide.pdf README.pdf INSTALL.pdf %.html: %.txt asciidoctor $< @@ -13,6 +24,12 @@ pdf: api-docs.pdf user-guide.pdf %.pdf: %.txt asciidoctor-pdf $< +%.html: ../%.md + pandoc $< -o $@ + +%.pdf: ../%.md + pandoc $< -t html5 -o $@ + clean: rm -f *.html *.pdf *~