Zoltar documentation site source

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.

Requirements (see Pipfile)

• Python 3
• pipenv
• MkDocs
• Material for MkDocs

Installation

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

Workflow

• Edit content located in the docs/ directory. Note: Only edit on the master branch, not the gh-pages one. The latter is overwritten by the mkdocs 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.

Hosts and servers

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.