Site set up

From scratch, clone and start a Python virtual environment.

$ git clone https://github.com/wilsjame/weblog.git
$ cd weblog
$ python3 -m venv .venv
$ source .venv/bin/activate

Sweet! Expect your prompt to look something like this
(.venv) sashabraus@laptop:~/weblog $

$ pip install -r requirements.txt
$ sudo apt install pandoc

pandoc is a markup converter required by nbsphinx
to output Jupyter Notebooks in html.

Build html

$ cd docs
$ make html

Everything to deploy a static site is in build/html
Refresh pathto/weblog/docs/build/html/index.html in your browser!

Add entry

  1. Create a new .rst (reStructuredText) file in the source directory

  2. Add the new .rst file to index.rst

$ cd docs/source
$ vi sitesetup.rst
$ vi index.rst

Given this index.rst snippet, sitesetup will appear after the binarysearch entry in the build html.

.. toctree::
   [...]

   welcome
   binarysearch
   sitesetup

Deploy

The current devops stack is:

local -> github -> travis ci -> aws s3 bucket -> public domain

Travis-CI

Sign up with your GitHub account and add a .travis.yml file to the root of the repository. Every main branch push to GitHub, Travis builds and deploys the site html to a public facing S3 bucket.

# working example .travis.yml
os: linux
dist: xenial
language: python
python:
  - "3.8"
install:
  - pip install -r requirements.txt
script:
  - cd docs &&
    make html
deploy:
    provider: s3
    access_key_id: $AWS_ACCESS_KEY_ID
    secret_access_key: $AWS_SECRET_ACCESS_KEY
    bucket: "wilsja.me"
    edge: true # opt in to dpl v2
    local_dir: ./build/html
    on:
        branch: main

The AWS (IAM) access key environment variables are set on travis-ci.com from the project’s settings page.

Host and DNS

The s3 -> domain step involves redirecting requests to a domain name, purchased from a registrar, to the S3 bucket serving site html. Set up varies depending on one’s choice of hosting and domain name services. I registered this domain with Namecheap, but consider keeping hosting and domain name services under the same umbrella for likely (well, hopefully!), easier integration and maintenance.