Add documentation using Sphinx, closes #9

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,31 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "adtl"
+copyright = "2023, Global.health"
+release = "0.4.0"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "myst_parser",
+    "sphinx_rtd_theme",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "venv"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/getting_started/installation.md

@@ -0,0 +1,29 @@
+---
+title: Installation
+---
+# Installation
+
+You can install this package using either [`pipx`](https://pypa.github.io/pipx/)
+or `pip`. Installing via `pipx` offers advantages if you want to just use the
+`adtl` tool standalone from the command line, as it isolates the Python
+package dependencies in a virtual environment. On the other hand, `pip` installs
+packages to the global environment which is generally not recommended as it
+can interfere with other packages on your system.
+
+* **Installation via `pipx`** (recommended):
+
+  ```shell
+  pipx install git+https://github.com/globaldothealth/adtl
+  ```
+
+* **Installation via `pip`**:
+
+  ```shell
+  python3 -m pip install git+https://github.com/globaldothealth/adtl
+  ```
+
+If you are writing code which depends on adtl (instead of using
+the command-line program), then it is best to add a dependency on
+`git+https://github.com/globaldothealth/adtl` to your Python build tool of
+choice.
+

docs/getting_started/usage.md

@@ -0,0 +1,36 @@
+---
+title: Usage
+---
+# Usage
+
+adtl can be used from the command line or as a Python library
+
+**As a CLI**:
+```bash
+adtl specification-file input-file
+```
+
+Here *specification-file* is the [parser specification](/specification) (as TOML or JSON)
+and *input-file* is the data file (not the data dictionary) that adtl
+will transform using the instructions in the specification.
+
+**As a Python library**:
+```python
+import adtl
+
+parser = adtl.Parser(specification)
+print(parser.tables) # list of tables created
+
+for row in parser.parse().read_table(table):
+    print(row)
+```
+
+If adtl is not in your PATH, this may give an error. Either add the location
+where the adtl script is installed to your PATH, or try running adtl as a module
+
+```shell
+python3 -m adtl specification-file input-file
+```
+
+Running adtl will create output files with the name of the parser, suffixed with
+table names in the current working directory.

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx==6.*
+sphinx-rtd-theme==1.*
+myst-parser==2.0.*

docs/specification.md

@@ -1,6 +1,9 @@
-# Specification format
+---
+title: Specification
+---
+# Specification
 
-The specification file describes the field mappings from the source file to the
+The ADTL specification describes the field mappings from the source file to the
 target schema. The format is under development and expected to change.
 
 Specification files can be in TOML or JSON, with TOML preferred due to readability.