Name: documentation
Owner: Mapzen
Description: Configuration files, tools, and content to build Mapzen's documentation
Created: 2015-07-29 22:40:53.0
Updated: 2018-01-26 17:34:26.0
Pushed: 2018-01-23 00:10:33.0
Homepage: https://mapzen.com/documentation
Size: 4810
Language: CSS
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
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.
| 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 |
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:
epare virtualenv and install local dependencies
ualenv -p python3 venv
ce venv/bin/activate
install -Ur requirements.txt
t all the sources and build all the documentation
e `make clean all` for a fresh build
cal preview
on -m http.server 8000
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.