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.

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.

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.