This repository holds documentation content for all aspects of Zoltar such as the web site user guide, help for researchers, API and client libraries, etc. The documentation source format is Markdown. We use Mkdocs uses to generate the static site.
To install required packages:
$ cd <readme.md's dir>
$ pipenv --three
$ pipenv shell
$ pipenv install
Pipfile was created via:
pipenv install mkdocs
pipenv install mkdocs-material
- Edit content located in the
docs/
directory. Note: Only edit on themaster
branch, not thegh-pages
one. The latter is overwritten by themkdocs gh-deploy
command when deploying (see below). - Preview the documentation locally. To run a local development server:
$ cd <readme.md's dir>
$ pipenv shell
$ mkdocs serve
- Commit and push your changes.
- Deploy to the GitHub Pages docs.zoltardata site
$ cd <readme.md's dir>
$ pipenv shell
$ mkdocs gh-deploy
- This should also update the custom domain site docs.zoltardata.com, which is currently hosted at Netlify.
Here are the moving parts that implement the documentation site:
- a GitHub repo docs.zoltardata to store doc source in Mkdocs flavored Markdown format
- the Mkdocs static site generator to build the site HTML from doc source
- a Netlify host to serve the built docs: docs-zoltardata-staging.netlify.com
- a docs.zoltardata.com subdomain configured on our DNSimple namespace server that points to the Netlify location. The dnsimple records are here and the Netlify domain configuration is here.