From 17f886a0be69a7730334e1518e6706e8f64ca14c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dra=C5=BEen=20Odoba=C5=A1i=C4=87?= Date: Sun, 26 Sep 2010 00:13:04 +0800 Subject: [PATCH] restructured documents according to documentation writing guidelines --- about_mapnik.rst | 15 ++++++---- getting_started.rst | 13 +++++---- index.rst | 12 ++++---- install_mapnik_library.rst | 24 ++++++++-------- install_mapnik_library_prereq.rst | 11 ++----- install_postgis_database.rst | 48 ++++++++++++++++++++----------- load_postgis_database.rst | 29 ++++++++++++++----- 7 files changed, 90 insertions(+), 62 deletions(-) diff --git a/about_mapnik.rst b/about_mapnik.rst index cb520e3..e06a994 100644 --- a/about_mapnik.rst +++ b/about_mapnik.rst @@ -1,6 +1,7 @@ +****** Mapnik -====== +****** Mapnik is about making beautiful maps. It uses the `AGG library `_ or `Cairo library @@ -13,8 +14,9 @@ parsing and so on, Mapnik doesn't re-invent the wheel, but utilizes best of breed industry standard libraries from http://boost.org. + History -------- +======= Mapnik was started in a warm June afternoon in 2005 by Artem Pavlenko. First version was released in ... @@ -22,8 +24,9 @@ Pavlenko. First version was released in ... Current version is 0.7.1 available for download at http://mapnik.org/download/. + Community ---------- +========= Mapnik community is organized around main site http://mapnik.org and development site http://trac.mapnik.org on which you can find latest @@ -43,7 +46,7 @@ If you like more direct communication you can find us on **#mapnik** at irc.freenode.net, feel free to drop in with your question anytime. Platforms ---------- +========= Mapnik is a cross platform toolkit that runs on Windows, Mac, and Linux (since release 0.4). Users commonly run Mapnik on Mac >=10.4.x @@ -51,7 +54,7 @@ Linux (since release 0.4). Users commonly run Mapnik on Mac >=10.4.x OpenSuse, and FreeBSD. Supported data formats ----------------------- +====================== Mapnik uses a plugin architecture to read different datasources. Current plugins which are considered stable, and built by @@ -91,7 +94,7 @@ cannot wait and/or like coding in C++, why not write your own data access plug-in? Future ------- +====== Large number of developers and contributors are actively developing *mapnik2* which will become **0.8.0**. Also, version **0.7.2** is diff --git a/getting_started.rst b/getting_started.rst index 5bb59b0..e2c0cc8 100644 --- a/getting_started.rst +++ b/getting_started.rst @@ -1,5 +1,6 @@ +*************** Getting Started -=============== +*************** After reading this document you should be able to create a simple rendered map using Python or C++. @@ -8,7 +9,7 @@ TODO: add final rendered image What do I need to get started? ------------------------------- +============================== First of all you need to install Mapnik library to your system. There are to two basic ways to do it, you can either download binaries or @@ -19,7 +20,7 @@ Installation depends on your operating system and following sections describe this process. Windows installation -^^^^^^^^^^^^^^^^^^^^ +-------------------- Installing Mapnik on windows consists of following steps: @@ -30,7 +31,7 @@ Installing Mapnik on windows consists of following steps: Each of this steps is explained in detail ..here..! Linux installation -^^^^^^^^^^^^^^^^^^ +------------------ Most modern Linux distributions include Mapnik binaries in their repositories. Installation method depends your distribution: @@ -48,14 +49,14 @@ repositories. Installation method depends your distribution: # pacman -S mapnik MacOSX installation -^^^^^^^^^^^^^^^^^^^ +------------------- Dane Springmeyer kindly hosts and builds MacOSX Mapnik binaries, you can find more information on his download page http://dbsgeo.com/downloads/. Testing Mapnik installation ---------------------------- +=========================== Easiest way to test if you have successfully installed and configured Mapnik is to start up your Python interpreter and try to import mapnik diff --git a/index.rst b/index.rst index 6887225..e7220dc 100644 --- a/index.rst +++ b/index.rst @@ -3,6 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +==================== Mapnik documentation ==================== @@ -15,21 +16,22 @@ algorithms/patterns for spatial data access and visualization. It can comfortably be used for both desktop and web development enabling fast-paced agile development. - +======== Contents ======== .. toctree:: - :maxdepth: 1 - - About Mapnik + :maxdepth: 2 + :numbered: + + about_mapnik.rst Getting Started Install PostGIS Database Load PostGIS Database with Initial Geographic Data Install Mapnik Library Prerequisites Install Mapnik Library - +================== Indices and tables ================== diff --git a/install_mapnik_library.rst b/install_mapnik_library.rst index d7dc009..035bee1 100644 --- a/install_mapnik_library.rst +++ b/install_mapnik_library.rst @@ -1,7 +1,9 @@ +********************** Install Mapnik Library ********************** -The Mapnik Library can be installed in several ways, choose only one of: +The Mapnik Library can be installed in several ways, choose only one +of: - Install from your package manager - Install from binaries @@ -18,9 +20,10 @@ Is everything up to date on your system? Install Mapnik Library from Package Manager -------------------------------------------- +=========================================== -This may not be the most recent version of Mapnik, depending on your distribution. +This may not be the most recent version of Mapnik, depending on your +distribution. :: @@ -28,9 +31,10 @@ This may not be the most recent version of Mapnik, depending on your distributio Install Mapnik Library from Binaries ------------------------------------- +==================================== -Windows and MacOSX binaries are available. See installation instructions for Windows and MacOSX. +Windows and MacOSX binaries are available. See installation +instructions for Windows and MacOSX. TODO: have build server create .deb, .rpm binaries @@ -41,7 +45,7 @@ Windows and MacOSX binaries are available. See installation instructions for Wi Install Latest Stable Mapnik Library from Source ------------------------------------------------- +================================================ :: @@ -54,7 +58,8 @@ Install Latest Stable Mapnik Library from Source sudo python scons/scons.py install sudo ldconfig -If Mapnik compiles without errors, confirm that python can find Mapnik. +If Mapnik compiles without errors, confirm that python can find +Mapnik. :: @@ -65,8 +70,3 @@ If Mapnik compiles without errors, confirm that python can find Mapnik. - - - - - diff --git a/install_mapnik_library_prereq.rst b/install_mapnik_library_prereq.rst index 00bfe07..0ef9ed9 100644 --- a/install_mapnik_library_prereq.rst +++ b/install_mapnik_library_prereq.rst @@ -1,8 +1,9 @@ +************************************ Install Mapnik Library Prerequisites ************************************ Install Boost Libraries from Packages -------------------------------------- +===================================== Is everything up to date on your system? @@ -35,11 +36,3 @@ Install Boost development libraries sudo aptitude install libboost-program-options1.40-dev - - - - - - - - diff --git a/install_postgis_database.rst b/install_postgis_database.rst index 55abcd1..423c3b6 100644 --- a/install_postgis_database.rst +++ b/install_postgis_database.rst @@ -1,8 +1,9 @@ +************************ Install PostGIS Database ************************ Install Postgresql and PostGIS ------------------------------- +============================== Is everything up to date on your system? @@ -11,19 +12,23 @@ Is everything up to date on your system? sudo aptitude update sudo aptitude safe-upgrade -Install Postgresql and the PostGIS extensions to enable geographical queries. +Install Postgresql and the PostGIS extensions to enable geographical +queries. :: sudo aptitude install postgresql-8.4-postgis postgresql-contrib-8.4 - sudo aptitude install postgresql-server-dev-8.4 - sudo aptitude install build-essential libxml2-dev + sudo aptitude install postgresql-server-dev-8.4 + sudo aptitude install build-essential libxml2-dev sudo aptitude install libgeos-dev libpq-dev libbz2-dev proj Configure the Postgresql Server -------------------------------- +=============================== -Edit the configuration file at /etc/postgresql/8.4/main/postgresql.conf to set some resonable defaults. These changes help when dealing with large quantities of data that are found in geographic some databases. +Edit the configuration file at +/etc/postgresql/8.4/main/postgresql.conf to set some resonable +defaults. These changes help when dealing with large quantities of +data that are found in geographic some databases. These edits are found in four places in the configuration file. @@ -35,7 +40,7 @@ These edits are found in four places in the configuration file. autovacuum = off Configure runtime kernel parameters ------------------------------------ +=================================== Edit /etc/sysctl.conf to set kernel parameters after a restart. @@ -50,9 +55,10 @@ Then apply the same kernel parameter now, without restarting. sudo sysctl kernel.shmmax=268435456 Restart the Postgresql Server ------------------------------ +============================= -Restart the postgresql database server to enable the configuration changes. +Restart the postgresql database server to enable the configuration +changes. :: @@ -64,9 +70,12 @@ The database server should restart without errors or warnings | ...done. Create the Postgresql Database ------------------------------- +============================== -Create a database called "gis". Some of our future tools presume that you will use this database name. Substitute your username for "username" in two places below. This should be the username that will render maps with mapnik. +Create a database called "gis". Some of our future tools presume that +you will use this database name. Substitute your username for +"username" in two places below. This should be the username that will +render maps with mapnik. :: @@ -77,7 +86,7 @@ Create a database called "gis". Some of our future tools presume that you will u exit Apply the PostGIS Extensions to the Database --------------------------------------------- +============================================ Apply the PostGIS extensions to the postgresql database. @@ -91,11 +100,13 @@ This should respond with many lines ending with | CREATE FUNCTION | COMMIT -Substitute your username for "username" in two places in the next line. This should be the username that will render maps with mapnik. +Substitute your username for "username" in two places in the next +line. This should be the username that will render maps with mapnik. :: - echo "ALTER TABLE geometry_columns OWNER TO username; ALTER TABLE spatial_ref_sys OWNER TO username;" | psql -d gis + echo "ALTER TABLE geometry_columns OWNER TO username; ALTER TABLE + spatial_ref_sys OWNER TO username;" | psql -d gis Should reply with @@ -103,9 +114,12 @@ Should reply with | ALTER TABLE Enable OpenStreetMap Updates ----------------------------- +============================ -This optional step is only required if you plan to use the OpenStreetMap regular data updates. Enable intarray to enable updates through the OpenStreetMap .osc files for daily, hourly and minutely updates. +This optional step is only required if you plan to use the +OpenStreetMap regular data updates. Enable intarray to enable updates +through the OpenStreetMap .osc files for daily, hourly and minutely +updates. :: @@ -118,7 +132,7 @@ Replies with many lines ending with | CREATE OPERATOR CLASS Set SRID for PostGIS Database ------------------------------ +============================= Set the Spatial Reference Identifier (SRID) on the new database. diff --git a/load_postgis_database.rst b/load_postgis_database.rst index ae6e43e..beb2df4 100644 --- a/load_postgis_database.rst +++ b/load_postgis_database.rst @@ -1,19 +1,27 @@ +************************************************** Load PostGIS Database with Initial Geographic Data ************************************************** -There are several ways to populate your geographic database. Choose only one of the following: +There are several ways to populate your geographic database. Choose +only one of the following: - OpenStreetMap "Planet" File - The OpenStreetMap "Planet" file contains data for the entire planet. This is a large file and can stress computers ( and first-time users ). + The OpenStreetMap "Planet" file contains data for the entire planet. + This is a large file and can stress computers ( and first-time users + ). - OpenStreetMap "Extract" File - OpenStreetMap "Extract" files contain the OpenStreetMap data for a single region, usually a single country, state or province. These are more managable than the "Planet" file while still often being substantial. + OpenStreetMap "Extract" files contain the OpenStreetMap data for a + single region, usually a single country, state or province. These + are more managable than the "Planet" file while still often being + substantial. - OpenStreetMap API Bounding Box - Smaller areas, sometimes town-sized, can be downloaded through the OpenStreetMap API. + Smaller areas, sometimes town-sized, can be downloaded through the + OpenStreetMap API. - Postgresql dump file @@ -21,12 +29,17 @@ There are several ways to populate your geographic database. Choose only one of OpenStreetMap Planet File ========================= -Aquire the complete OpenStreetMap database, also called the "planet file" and load it in to the PostGIS database. +Aquire the complete OpenStreetMap database, also called the "planet +file" and load it in to the PostGIS database. Aquire the Planet File ---------------------- -A new "planet" file is published approximately each week. The mirror and archives of the "planet" files are found at http://planet.openstreetmap.org/ . In July 2010 the planet file was about 10GB in length. If you are not interested in the entire planet you can choose to download an extract file instead. +A new "planet" file is published approximately each week. The mirror +and archives of the "planet" files are found at +http://planet.openstreetmap.org/ . In July 2010 the planet file was +about 10GB in length. If you are not interested in the entire planet +you can choose to download an extract file instead. Install the Planet File ----------------------- @@ -37,7 +50,9 @@ Using osm2pgsql or another tool. OpenStreetMap Extract File ========================== -OpenStreetMap Extract files typically include a single country, state or province. They are published periodically by various sites including +OpenStreetMap Extract files typically include a single country, state +or province. They are published periodically by various sites +including - http://download.geofabrik.de/osm/ - http://download.cloudmade.com/