From: marc tobias <mtmail@gmx.net>
Date: Fri, 19 Jul 2019 17:27:23 +0000 (+0200)
Subject: New readme file on how to build the documentation
X-Git-Tag: v3.4.0~24^2
X-Git-Url: https://git.openstreetmap.org/nominatim.git/commitdiff_plain/3b39cfb1cf67294d4374944a22d0ff89b8617ba2

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
index 00000000..6e792c25
--- /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 ef39bcb7..49cd6e72 100644
--- 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'