Mapzen documentation

This repository contains the configuration files and tools used to build Mapzen's documentation site mapzen.com/documentation.

The documentation is built with an open-source Python tool called MkDocs, which formats GitHub markdown files in to a static, HTML website. Note that while MkDocs reads just one source, Mapzen has enhanced it to integrate multiple repositories. There have been additional enhancements to support URL redirects and renaming files in the output help. You can read more about this process in the blog post.

As long as a markdown file is listed in the build configuration, changes in the source files in the GitHub branch that is being pulled into the help (typically, the master branch) appear automatically on https://mapzen.com/documentation. This is through continuous integration processes that run in the source respositories and in this one.

Source file locations

The source files to build Mapzen's documentation may be found in separate documentation repositories in a GitHub organization, as a documentation folder in a project's repository, or within this repository. Getting changes onto the documentation site may require the files be on a certain branch or in a release.

Documentation section	Source location	Branch name or release
Overview	https://github.com/mapzen/mapzen-docs-generator/tree/master/docs	Master
mapzen.js	https://github.com/mapzen/mapzen.js/tree/master/docs	Latest release
Tangram	https://github.com/tangrams/tangram-docs	gh-pages
Vector tiles	https://github.com/tilezen/vector-datasource/tree/master/docs	Latest release
Search	https://github.com/pelias/pelias-doc	Master
Mobility	https://github.com/valhalla/valhalla-docs	Master
Metro Extracts	https://github.com/mapzen/metro-extracts/tree/master/docs	Master
Terrain tiles	https://github.com/tilezen/joerd	Latest release
Elevation	https://github.com/valhalla/valhalla-docs	Master
Android SDK	https://github.com/mapzen/android/tree/master/docs	Master
iOS SDK	https://github.com/mapzen/ios/blob/master/docs	Master
Address parsing/libpostal	https://github.com/whosonfirst/go-whosonfirst-libpostal/blob/master/docs	Master
Who's On First	https://github.com/whosonfirst/whosonfirst-www-api/tree/master/docs	Master
Cartography	https://github.com/tangrams/cartography-docs/	Master

Build locally

If you need to build the documentation locally for testing, clone this repository and open a terminal window to the documentation folder.

On a Mac, assuming you have Homebrew and Python 3 installed, and a local checkout of this repository:

# Prepare virtualenv and install local dependencies
virtualenv -p python3 venv
source venv/bin/activate
pip install -Ur requirements.txt

# Get all the sources and build all the documentation
make

# Use `make clean all` for a fresh build

# Local preview
python -m http.server 8000
open http://localhost:8000/dist/

Run make clean all to build a clean copy of the documentation. This command deletes the previous build and makes new files.

You may be able to build one section of the documentation using make clean dist-{projectname}, such as make clean dist-tangram.