New readme file on how to build the documentation

diff --git a/docs/develop/Documentation.md b/docs/develop/Documentation.md
new file mode 100644 (file)
index 0000000..6e792c2
--- /dev/null
+++ b/docs/develop/Documentation.md
@@ -0,0 +1,36 @@
+# Documentation Pages
+
+The [Nominatim documentation](https://nominatim.org/release-docs/develop/) is built using the [MkDocs](https://www.mkdocs.org/) static site generation framework. The master branch is automatically deployed every night on under [https://nominatim.org/release-docs/develop/]()
+
+To preview local changes:
+
+1. Install MkDocs
+
+   ```
+   pip3 install --user mkdocs 
+   ```
+
+
+2. In build directory run
+
+   ```
+   make doc
+   INFO - Cleaning site directory
+   INFO - Building documentation to directory: /home/vagrant/build/site-html 
+   ```
+
+   This runs `mkdocs build` plus extra transformion of some files and adds symlinks (see `CMakeLists.txt` for the exact steps).
+
+
+3. Start webserver for local testing
+
+   ```
+   mkdocs serve
+   [server:296] Serving on http://127.0.0.1:8000
+   [handlers:62] Start watching changes
+   ```
+
+   If you develop inside a Vagrant virtual machine:
+   * add port forwarding to your Vagrantfile, e.g. `config.vm.network "forwarded_port", guest: 8000, host: 8000`
+   * use `mkdocs serve --dev-addr 0.0.0.0:8000` because the default localhost
+      IP does not get forwarded.

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index ef39bcb7ddc6b77b2651c3e3fe33d5171e3c0b95..49cd6e72da8a6fd64cdf27ddd3103f7e70eab58e 100644 (file)
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -22,6 +22,7 @@ pages:
         - 'Overview' : 'develop/overview.md'
         - 'OSM Data Import' : 'develop/Import.md'
         - 'Place Ranking' : 'develop/Ranking.md'
+        - 'Documentation' : 'develop/Documentation.md'
     - 'External Data Sources':
         - 'Overview' : 'data-sources/overview.md'
         - 'US Census (Tiger)': 'data-sources/US-Tiger.md'