Put install instructions of test tools into separate docs/ markdown file

diff --git a/docs/admin/Advanced-Installations.md b/docs/admin/Advanced-Installations.md
index 8486b6a234d29620631d2af88beac2bd8e895b77..ee3a799238edf8bbc43bb80d4063f2ef77feedb3 100644 (file)
--- a/docs/admin/Advanced-Installations.md
+++ b/docs/admin/Advanced-Installations.md
@@ -105,5 +105,5 @@ This will get diffs from the replication server, import diffs and index the data
 
 ## Verification and further setup
 
 
 ## Verification and further setup
 

-Instructions for import verification and other details like importing Wikidata can be found in [import and update page](Import-and-Update.md)
+Instructions for import verification and other details like importing Wikidata can be found in [import page](Import.md)

 
 

diff --git a/docs/admin/Import-and-Update.md b/docs/admin/Import.md
similarity index 80%
rename from docs/admin/Import-and-Update.md
rename to docs/admin/Import.md
index 47516a2b006d19c1cc66e44df46dd8663431d6ea..bcc33af81e05aee601d8fb88144151f9488c7b04 100644 (file)
--- a/docs/admin/Import-and-Update.md
+++ b/docs/admin/Import.md
@@ -1,4 +1,4 @@
-# Importing and Updating the Database
+# Importing the Database

 
 The following instructions explain how to create a Nominatim database
 from an OSM planet file and how to keep the database up to date. It
 
 The following instructions explain how to create a Nominatim database
 from an OSM planet file and how to keep the database up to date. It


@@ -253,70 +253,3 @@ entire US adds about 10GB to your database.
 ```
 
 
 ```
 
 

-## Updates
-
-There are many different ways to update your Nominatim database.
-The following section describes how to keep it up-to-date with Pyosmium.
-For a list of other methods see the output of `./utils/update.php --help`.
-
-!!! warning
-    If you have configured a flatnode file for the import, then you
-    need to keep this flatnode file around for updates as well.
-
-#### Installing the newest version of Pyosmium
-
-It is recommended to install Pyosmium via pip. Make sure to use python3.
-Run (as the same user who will later run the updates):
-
-```sh
-pip3 install --user osmium
-```
-
-Nominatim needs a tool called `pyosmium-get-updates` which comes with
-Pyosmium. You need to tell Nominatim where to find it. Add the
-following line to your `settings/local.php`:
-
-    @define('CONST_Pyosmium_Binary', '/home/user/.local/bin/pyosmium-get-changes');
-
-The path above is fine if you used the `--user` parameter with pip.
-Replace `user` with your user name.
-
-#### Setting up the update process
-
-Next the update needs to be initialised. By default Nominatim is configured
-to update using the global minutely diffs.
-
-If you want a different update source you will need to add some settings
-to `settings/local.php`. For example, to use the daily country extracts
-diffs for Ireland from Geofabrik add the following:
-
-    // base URL of the replication service
-    @define('CONST_Replication_Url', 'https://download.geofabrik.de/europe/ireland-and-northern-ireland-updates');
-    // How often upstream publishes diffs
-    @define('CONST_Replication_Update_Interval', '86400');
-    // How long to sleep if no update found yet
-    @define('CONST_Replication_Recheck_Interval', '900');
-
-To set up the update process now run the following command:
-
-    ./utils/update.php --init-updates
-
-It outputs the date where updates will start. Recheck that this date is
-what you expect.
-
-The `--init-updates` command needs to be rerun whenever the replication service
-is changed.
-
-#### Updating Nominatim
-
-The following command will keep your database constantly up to date:
-
-    ./utils/update.php --import-osmosis-all
-
-(Note that even though the old name "import-osmosis-all" has been kept for
-compatibility reasons, Osmosis is not required to run this - it uses pyosmium
-behind the scenes.)
-
-If you have imported multiple country extracts and want to keep them
-up-to-date, [Advanced installations section](Advanced-Installations.md) contains instructions 
-to set up and update multiple country extracts.

diff --git a/docs/admin/Installation.md b/docs/admin/Installation.md
index cf994c4c7a6b8fe7c4cc27d59d30fb55d09b4d88..bc97212ee2d663dc4cd1dc0c5556eb3e432c30ba 100644 (file)
--- a/docs/admin/Installation.md
+++ b/docs/admin/Installation.md
@@ -188,4 +188,4 @@ Restart the nginx and php5-fpm services and the website should now be available
 at `http://localhost/`.
 
 
 at `http://localhost/`.
 
 

-Now continue with [importing the database](Import-and-Update.md).
+Now continue with [importing the database](Import.md).

diff --git a/docs/admin/Update.md b/docs/admin/Update.md
new file mode 100644 (file)
index 0000000..8cc2b34
--- /dev/null
+++ b/docs/admin/Update.md
@@ -0,0 +1,67 @@
+# Updating the Database
+
+There are many different ways to update your Nominatim database.
+The following section describes how to keep it up-to-date with Pyosmium.
+For a list of other methods see the output of `./utils/update.php --help`.
+
+!!! warning
+    If you have configured a flatnode file for the import, then you
+    need to keep this flatnode file around for updates as well.
+
+#### Installing the newest version of Pyosmium
+
+It is recommended to install Pyosmium via pip. Make sure to use python3.
+Run (as the same user who will later run the updates):
+
+```sh
+pip3 install --user osmium
+```
+
+Nominatim needs a tool called `pyosmium-get-updates` which comes with
+Pyosmium. You need to tell Nominatim where to find it. Add the
+following line to your `settings/local.php`:
+
+    @define('CONST_Pyosmium_Binary', '/home/user/.local/bin/pyosmium-get-changes');
+
+The path above is fine if you used the `--user` parameter with pip.
+Replace `user` with your user name.
+
+#### Setting up the update process
+
+Next the update needs to be initialised. By default Nominatim is configured
+to update using the global minutely diffs.
+
+If you want a different update source you will need to add some settings
+to `settings/local.php`. For example, to use the daily country extracts
+diffs for Ireland from Geofabrik add the following:
+
+    // base URL of the replication service
+    @define('CONST_Replication_Url', 'https://download.geofabrik.de/europe/ireland-and-northern-ireland-updates');
+    // How often upstream publishes diffs
+    @define('CONST_Replication_Update_Interval', '86400');
+    // How long to sleep if no update found yet
+    @define('CONST_Replication_Recheck_Interval', '900');
+
+To set up the update process now run the following command:
+
+    ./utils/update.php --init-updates
+
+It outputs the date where updates will start. Recheck that this date is
+what you expect.
+
+The `--init-updates` command needs to be rerun whenever the replication service
+is changed.
+
+#### Updating Nominatim
+
+The following command will keep your database constantly up to date:
+
+    ./utils/update.php --import-osmosis-all
+
+(Note that even though the old name "import-osmosis-all" has been kept for
+compatibility reasons, Osmosis is not required to run this - it uses pyosmium
+behind the scenes.)
+
+If you have imported multiple country extracts and want to keep them
+up-to-date, [Advanced installations section](Advanced-Installations.md) contains instructions 
+to set up and update multiple country extracts.

diff --git a/docs/develop/Documentation.md b/docs/develop/Documentation.md
index df8d2b1a84f05a8dab945f3b100d9935deea5b1a..debe6858a43f6def7939b4a9ef45056ff0ba36d8 100644 (file)
--- a/docs/develop/Documentation.md
+++ b/docs/develop/Documentation.md
@@ -8,6 +8,9 @@ To preview local changes, first install MkDocs
 pip3 install --user mkdocs
 ```
 
 pip3 install --user mkdocs
 ```
 

+If `mkdocs` can't be found after the installation, the $PATH might have not
+be set correctly yet. Try opening a new terminal session.
+

 
 Then go to the build directory and run
 
 
 Then go to the build directory and run
 

diff --git a/docs/develop/Setup.md b/docs/develop/Setup.md
new file mode 100644 (file)
index 0000000..53a084d
--- /dev/null
+++ b/docs/develop/Setup.md
@@ -0,0 +1,46 @@
+# Setup Test Environment
+
+To test changes and contribute to Nominatim you should be able to run
+the test suite(s). For many usecases it's enough to create a Vagrant
+virtual machine (see `VAGRANT.md`), import one small country into the
+database.
+
+## Prerequisites
+
+Nominatim supports a range of PHP versions and PHPUnit versions also
+move fast. We try to test against the newest stable PHP release and
+PHPUnit version even though we expect many Nominatim users will install
+older version on their production servers.
+
+#### Ubuntu 20
+
+    sudo apt-get install -y phpunit php-codesniffer php-cgi
+    pip3 install --user behave nose
+
+#### Ubuntu 18
+
+    pip3 install --user behave nose
+
+    sudo apt-get install -y composer php-cgi php-cli php-mbstring php-xml zip unzip
+
+    composer global require "squizlabs/php_codesniffer=*"
+    sudo ln -s ~/.config/composer/vendor/bin/phpcs /usr/bin/
+
+    composer global require "phpunit/phpunit=8.*"
+    sudo ln -s ~/.config/composer/vendor/bin/phpunit /usr/bin/
+
+
+#### CentOS 7 or 8
+
+    sudo dnf install -y php-dom php-mbstring
+    pip3 install --user behave nose
+
+    composer global require "squizlabs/php_codesniffer=*"
+    sudo ln -s ~/.config/composer/vendor/bin/phpcs /usr/bin/
+
+    composer global require "phpunit/phpunit=^7"
+    sudo ln -s ~/.config/composer/vendor/bin/phpunit /usr/bin/
+
+## Run tests, code linter, code coverage
+
+See `README.md` in `test` subdirectory.

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 16a675385eea046e20d96a897d1125f806bdb19e..0a411306b4c4e043be908259de7ed124a717c70e 100644 (file)
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -16,7 +16,8 @@ pages:
         - 'FAQ': 'api/Faq.md'
     - 'Administration Guide':
         - 'Basic Installation': 'admin/Installation.md'
         - 'FAQ': 'api/Faq.md'
     - 'Administration Guide':
         - 'Basic Installation': 'admin/Installation.md'

-        - 'Importing and Updating' : 'admin/Import-and-Update.md'
+        - 'Importing' : 'admin/Import.md'
+        - 'Updating' : 'admin/Update.md'

         - 'Nominatim UI'  : 'admin/Setup-Nominatim-UI.md'
         - 'Advanced Installations' : 'admin/Advanced-Installations.md'
         - 'Migration from older Versions' : 'admin/Migration.md'
         - 'Nominatim UI'  : 'admin/Setup-Nominatim-UI.md'
         - 'Advanced Installations' : 'admin/Advanced-Installations.md'
         - 'Migration from older Versions' : 'admin/Migration.md'


@@ -26,6 +27,7 @@ pages:
         - 'OSM Data Import' : 'develop/Import.md'
         - 'Place Ranking' : 'develop/Ranking.md'
         - 'Postcodes' : 'develop/Postcodes.md'
         - 'OSM Data Import' : 'develop/Import.md'
         - 'Place Ranking' : 'develop/Ranking.md'
         - 'Postcodes' : 'develop/Postcodes.md'

+        - 'Setup Test Environment' : 'develop/Setup.md'

         - 'Documentation' : 'develop/Documentation.md'
     - 'External Data Sources':
         - 'Overview' : 'data-sources/overview.md'
         - 'Documentation' : 'develop/Documentation.md'
     - 'External Data Sources':
         - 'Overview' : 'data-sources/overview.md'

diff --git a/vagrant/Install-on-Centos-7.sh b/vagrant/Install-on-Centos-7.sh
index e2592f6591412f3cf9284a14564a87c667821b10..7ce09727c9dec9b14dac1b8513ef28d80997ced0 100755 (executable)
--- a/vagrant/Install-on-Centos-7.sh
+++ b/vagrant/Install-on-Centos-7.sh
@@ -48,18 +48,6 @@
 
     pip3 install --user psycopg2 pytidylib
 
 
     pip3 install --user psycopg2 pytidylib
 

-# If you want to run the test suite, you need to install the following
-# additional packages:
-
-#DOCS:    :::sh
-    sudo yum install -y php-dom php-mbstring
-    pip3 install --user behave nose
-
-    composer global require "squizlabs/php_codesniffer=*"
-    sudo ln -s ~/.config/composer/vendor/bin/phpcs /usr/bin/
-
-    composer global require "phpunit/phpunit=7.*"
-    sudo ln -s ~/.config/composer/vendor/bin/phpunit /usr/bin/

 
 #
 # System Configuration
 
 #
 # System Configuration


@@ -214,4 +202,4 @@ EOF
 
 
 # Nominatim is now ready to use. Continue with
 
 
 # Nominatim is now ready to use. Continue with

-# [importing a database from OSM data](../admin/Import-and-Update.md).
+# [importing a database from OSM data](../admin/Import.md).

diff --git a/vagrant/Install-on-Centos-8.sh b/vagrant/Install-on-Centos-8.sh
index cf7371edf88760545352c93cb89eaacec8a1ae33..75b7a558c8617be69cc4b0e2afd175c5f8693e8d 100755 (executable)
--- a/vagrant/Install-on-Centos-8.sh
+++ b/vagrant/Install-on-Centos-8.sh
@@ -41,18 +41,6 @@
 
     pip3 install --user psycopg2 pytidylib
 
 
     pip3 install --user psycopg2 pytidylib
 

-# If you want to run the test suite, you need to install the following
-# additional packages:
-
-#DOCS:    :::sh
-    sudo dnf install -y php-dom php-mbstring
-    pip3 install --user behave nose
-
-    composer global require "squizlabs/php_codesniffer=*"
-    sudo ln -s ~/.config/composer/vendor/bin/phpcs /usr/bin/
-
-    composer global require "phpunit/phpunit=^7"
-    sudo ln -s ~/.config/composer/vendor/bin/phpunit /usr/bin/

 
 #
 # System Configuration
 
 #
 # System Configuration


@@ -208,4 +196,4 @@ EOF
 
 
 # Nominatim is now ready to use. Continue with
 
 
 # Nominatim is now ready to use. Continue with

-# [importing a database from OSM data](../admin/Import-and-Update.md).
+# [importing a database from OSM data](../admin/Import.md).

diff --git a/vagrant/Install-on-Ubuntu-18.sh b/vagrant/Install-on-Ubuntu-18.sh
index 02a1c738158dc66aa6560bb6f553e45946c0dc2a..34e6aaa05de10b3b9fcb4dad0fb789eb452d9132 100755 (executable)
--- a/vagrant/Install-on-Ubuntu-18.sh
+++ b/vagrant/Install-on-Ubuntu-18.sh
@@ -33,18 +33,6 @@ export DEBIAN_FRONTEND=noninteractive #DOCS:
                             php-intl python3-setuptools python3-dev python3-pip \
                             python3-psycopg2 python3-tidylib git
 
                             php-intl python3-setuptools python3-dev python3-pip \
                             python3-psycopg2 python3-tidylib git
 

-# If you want to run the test suite, you need to install the following
-# additional packages including the PHP package manager composer:
-
-    pip3 install --user behave nose
-
-    sudo apt-get install -y composer php-cgi php-cli php-mbstring php-xml zip unzip
-
-    composer global require "squizlabs/php_codesniffer=*"
-    sudo ln -s ~/.config/composer/vendor/bin/phpcs /usr/bin/
-
-    composer global require "phpunit/phpunit=8.*"
-    sudo ln -s ~/.config/composer/vendor/bin/phpunit /usr/bin/

 
 #
 # System Configuration
 
 #
 # System Configuration


@@ -173,4 +161,4 @@ EOF
 
 
 # Nominatim is now ready to use. Continue with
 
 
 # Nominatim is now ready to use. Continue with

-# [importing a database from OSM data](../admin/Import-and-Update.md).
+# [importing a database from OSM data](../admin/Import.md).

diff --git a/vagrant/Install-on-Ubuntu-20.sh b/vagrant/Install-on-Ubuntu-20.sh
index c124b159cd0e338795b7f396677181bcec33fb55..a7029be2e88a8c11167c7590d60e7a5cf5bbe29b 100644 (file)
--- a/vagrant/Install-on-Ubuntu-20.sh
+++ b/vagrant/Install-on-Ubuntu-20.sh
@@ -35,12 +35,6 @@ export DEBIAN_FRONTEND=noninteractive #DOCS:
                             php-intl python3-setuptools python3-dev python3-pip \
                             python3-psycopg2 python3-tidylib git
 
                             php-intl python3-setuptools python3-dev python3-pip \
                             python3-psycopg2 python3-tidylib git
 

-# If you want to run the test suite, you need to install the following
-# additional packages:
-
-    sudo apt-get install -y phpunit php-codesniffer php-cgi
-
-    pip3 install --user behave nose

 #
 # System Configuration
 # ====================
 #
 # System Configuration
 # ====================


@@ -168,4 +162,4 @@ EOF
 
 
 # Nominatim is now ready to use. Continue with
 
 
 # Nominatim is now ready to use. Continue with

-# [importing a database from OSM data](../admin/Import-and-Update.md).
+# [importing a database from OSM data](../admin/Import.md).