documentation
documentation copied to clipboard
mapzen
Configuration files, tools, and content to build Mapzen's documentation
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.
mapzen