minimal docker setup to build docs locally

Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3
+
+WORKDIR /usr/src/mds
+
+COPY . .
+
+RUN apt-get update -y && \
+    pip install --upgrade pip && \
+    pip install pipenv && \
+    pipenv update --dev

Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = ./docs
+BUILDDIR      = ./docs/_build
+
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

Pipfile

@@ -3,14 +3,12 @@ url = "https://pypi.org/simple"
 verify_ssl = true
 name = "pypi"
 
-[packages]
-
 [dev-packages]
-sphinx = "*"
+mds-provider = {path = ".", editable = true}
 recommonmark = "*"
 requests = "*"
+sphinx = "*"
 sphinx-rtd-theme = "*"
-mds-provider = {path = "."}
 
 [requires]
-python_version = "3.6"
+python_version = "3.6"

README.md

@@ -38,7 +38,31 @@ python setup.py install
 | [`mds.schemas`](mds/schemas.py) | Validate data using the [JSON schemas][schemas] |
 | [`mds.versions`](mds/versions.py) | Work with [MDS versions][versions] |
 
+## Generating documentation
+
+`mds-provider` uses [Sphinx][sphinx] for documentation generation. We provide a minimal Docker setup for building and
+serving documentation locally:
+
+```bash
+docker-compose run [--rm] docs
+```
+
+After the first-time image build, and subsequent Sphinx build(s), view the docs at http://localhost:8000
+
+To rebuild after a code change, run the command again:
+
+```bash
+docker-compose run [--rm] docs
+```
+
+To bring down the local server:
+
+```bash
+docker-compose down
+```
+
 [provider]: https://github.com/CityOfLosAngeles/mobility-data-specification/tree/master/provider
 [registry]: https://github.com/CityofLosAngeles/mobility-data-specification/blob/master/providers.csv
 [schemas]: https://github.com/CityOfLosAngeles/mobility-data-specification/tree/master/generate_schema
+[sphinx]: http://www.sphinx-doc.org/en/stable/
 [versions]: https://github.com/CityofLosAngeles/mobility-data-specification/releases

docker-compose.yml

@@ -0,0 +1,16 @@
+version: "3.7"
+services:
+  docs:
+    build: .
+    working_dir: /usr/src/mds
+    depends_on:
+      - nginx
+    command: pipenv run make html
+    volumes:
+      - .:/usr/src/mds
+  nginx:
+    image: nginx:latest
+    ports:
+      - 8000:80
+    volumes:
+      - ./docs/_build/html:/usr/share/nginx/html

docs/conf.py

@@ -23,11 +23,11 @@
 copyright = '2018, City of Santa Monica'
 author = 'City of Santa Monica'
 
-import mds
+import mds.versions
 # The short X.Y version
-version = mds.VERSION()
+version = mds.Version.library().header
 # The full version, including alpha/beta/rc tags
-release = mds.VERSION()
+release = str(mds.Version.library())
 
 
 # -- General configuration ---------------------------------------------------