From 3b39cfb1cf67294d4374944a22d0ff89b8617ba2 Mon Sep 17 00:00:00 2001 From: marc tobias Date: Fri, 19 Jul 2019 19:27:23 +0200 Subject: [PATCH] New readme file on how to build the documentation --- docs/develop/Documentation.md | 36 +++++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 1 + 2 files changed, 37 insertions(+) create mode 100644 docs/develop/Documentation.md 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' -- 2.39.5