docs/develop/Documentation.md

   1 # Documentation Pages
   2
   3 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/](https://nominatim.org/release-docs/develop/)
   4
   5 To preview local changes, first install MkDocs
   6
   7 ```
   8 pip3 install --user mkdocs
   9 ```
  10
  11 If `mkdocs` can't be found after the installation, the $PATH might have not
  12 been set correctly yet. Try opening a new terminal session.
  13
  14
  15 Then go to the build directory and run
  16
  17 ```
  18 make doc
  19 INFO - Cleaning site directory
  20 INFO - Building documentation to directory: /home/vagrant/build/site-html
  21 ```
  22
  23 This runs `mkdocs build` plus extra transformation of some files and adds
  24 symlinks (see `CMakeLists.txt` for the exact steps).
  25
  26 Now you can start webserver for local testing
  27
  28 ```
  29 build> mkdocs serve
  30 [server:296] Serving on http://127.0.0.1:8000
  31 [handlers:62] Start watching changes
  32 ```
  33
  34 If you develop inside a Vagrant virtual machine:
  35
  36  * add port forwarding to your Vagrantfile,
  37    e.g. `config.vm.network "forwarded_port", guest: 8000, host: 8000`
  38  * use `mkdocs serve --dev-addr 0.0.0.0:8000` because the default localhost
  39    IP does not get forwarded.