rst docs for #5

.github/workflows/deploy.yaml

@@ -1,41 +1,48 @@
 # https://github.com/rust-lang/mdBook/wiki/Automated-Deployment%3A-GitHub-Actions#github-pages-deploy
-name: Deploy
+name: Render
 on:
   push:
     branches:
       - main
+  pull_request:
+    branches:
+      - main
 
 jobs:
-  deploy:
+
+  render:
+
     runs-on: ubuntu-latest
+
     permissions:
       contents: write  # To push a branch 
       pull-requests: write  # To create a PR from that branch
+
     steps:
+
     - uses: actions/checkout@v3
       with:
         fetch-depth: 0
-    - name: Install latest mdbook
+
+    - name: Install Python dependencies
+      uses: py-actions/py-dependency-install@v4
+      with:
+        path: "requirements.txt"
+
+    - name: make docs and cname
       run: |
-        tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
-        url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
-        mkdir mdbook
-        curl -sSL $url | tar -xz --directory=./mdbook
-        echo `pwd`/mdbook >> $GITHUB_PATH
+        make html
+        echo 'docs.urbananalyst.city' > _build/html/CNAME
+
+    - name: Upload artifaces
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: _build/html/
+
     - name: Deploy GitHub Pages
-      run: |
-        # This assumes your book is in the root of your repository.
-        # Just add a `cd` here if you need to change to another directory.
-        mdbook build
-        git worktree add gh-pages
-        git config user.name "Deploy from CI"
-        git config user.email ""
-        cd gh-pages
-        # Delete the ref to avoid keeping history.
-        git update-ref -d refs/heads/gh-pages
-        rm -rf *
-        mv ../book/* .
-        echo 'docs.urbananalyst.city' > CNAME
-        git add .
-        git commit -m "Deploy $GITHUB_SHA to gh-pages"
-        git push --force --set-upstream origin gh-pages
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: _build/html

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)

conf.py

@@ -0,0 +1,75 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'urban analyst docs'
+copyright = '2024, Mark Padgham'
+author = 'Mark Padgham'
+
+# The full version, including alpha/beta/rc tags
+release = '0.0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+]
+
+myst_enable_extensions = [
+    'colon_fence',
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.md', 'aaa*']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

src/data.md → data.rst

@@ -1,15 +1,16 @@
-# Data Sources
+5. Data Sources
+###############
 
 The Urban Analyst platform aims to be applicable to as much of the world as
 possible. To achieve this, data sources are chosen which are ideally have
 global coverage, and which are not specific to any one city. The global sources used are:
 
-- [Open Street Map](https://openstreetmap.org) for all data on traversable
+- `Open Street Map <https://openstreetmap.org>`_ for all data on traversable
   ways, natural spaces, parking infrastructure, and locations of schools.
-- Population density data from the [European Union *Global Human Settlement
-  Layer*](https://ghsl.jrc.ec.europa.eu/index.php).
-- Elevation data from [NASA Earth Observation
-  Data](https://www.earthdata.nasa.gov/), used to include effects of incline
+- Population density data from the `European Union *Global Human Settlement
+  Layer* <https://ghsl.jrc.ec.europa.eu/index.php>`_.
+- Elevation data from `NASA Earth Observation
+  Data <https://www.earthdata.nasa.gov/>`_, used to include effects of incline
   on both pedestrian and bicycle travel times.
 
 The following additional data are then required for each city:
@@ -24,7 +25,7 @@ The last of these data requirements is the most restrictive, as most cities of
 the world do not have or provide public transport data in GTFS format. There
 are nevertheless thousands of cities which do provide GTFS feeds, as can be
 seen for example in the GTFS feed aggregation platform
-[transit.land](https://transit.land).
+`transit.land <https://transit.land>`_.
 
 For USA cities, data for the additional two variables of housing value and
 rental price per room are obtained from US Government census data.