refactor: Replace Jekyll, support piecemeal AIP format. (aip-dev#540)

refactor: Replace Jekyll, support piecemeal AIP format.

Author: Luke Sneeringer

.dockerignore

@@ -6,9 +6,6 @@
 Dockerfile
 .dockerignore
 
-# Ruby & Jekyll scaffolding
-_site
-
 # Translations
 *.mo
 

.github/workflows/publish.yaml

@@ -0,0 +1,23 @@
+---
+name: publish
+on:
+  push:
+    branches: master
+jobs:
+  github-pages:
+    runs-on: ubuntu-latest
+    container: python:3.8
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install system dependencies.
+        run: apt-get update && apt-get install -y rsync
+      - name: Install the site generator.
+        run: pip install -r requirements.txt
+      - name: Build the static site.
+        run: aip-site-gen . out
+      - name: Publish the static site to GitHub Pages.
+        uses: jamesives/github-pages-deploy-action@releases/v3
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: out

.github/workflows/test.yaml

@@ -0,0 +1,15 @@
+---
+name: test
+on:
+  pull_request:
+    branches: master
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container: python:3.8
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install the site-generator
+        run: pip install -r requirements.txt
+      - name: Build the site.
+        run: aip-site-gen . /out

.gitignore

@@ -1,8 +1,7 @@
-# Jekyll
-default.profraw
-_site
-.jekyll-metadata
+# pytest
+site/.coverage
+site/.pytest_cache
+site/htmlcov
 
-# npm
-node_modules/
-*/package-lock.json
+# mypy
+.mypy_cache

CONTRIBUTING.md

@@ -4,12 +4,12 @@ We'd love to accept your patches and contributions to this project.
 
 ## Development Environment
 
-If you are contributing documentation (rather than samples) and want to be able
-to view it in your browser, the easiest way to do so is to run the provided
+If you are contributing AIP content (rather than code) and want to be able to
+view it in your browser, the easiest way to do so is to run the provided
 development server.
 
-We use [GitHub Pages][1] to make this documentation available, which uses
-[Jekyll][2] under the hood.
+We use [GitHub Pages][1] to make this documentation available, and a specific
+[site generator][2] to build the site.
 
 If you have [Docker][3] installed, clone this repository and run the `serve.sh`
 file at the root of the repository. This script does two things:
@@ -18,45 +18,35 @@ file at the root of the repository. This script does two things:
   as `aip-site`.
 - It runs the `aip-site` image.
 
-The Jekyll development server uses port 4000 by default; point your web browser
-to `http://localhost:4000`, and you should see the site.
+The development server uses port 4000; point your web browser to
+`http://localhost:4000`, and you should see the site.
 
 **Note:** After building the Docker image for the first time, you may
-experience issues if Ruby dependencies change underneath you. If this happens,
-remove your Docker image (`docker rmi aip-site`) and run `serve.sh` again.
+experience issues if Python dependencies change underneath you. If this
+happens, remove your Docker image (`docker rmi aip-site`) and run `serve.sh`
+again.
 
 ### Arguments
 
-Any arguments provided to `serve.sh` (or `docker run`) are forwarded to Jekyll.
-Note that the Docker entrypoint automatically provides `--destination` and
-`--host` arguments, and you should not change these. Additionally, changing
-ports is not advised (call `docker run` yourself with a customized `-p` switch
-if you need to use custom ports).
+Any arguments provided to `serve.sh` (or `docker run`) are forwarded (however,
+the current site generator does not honor any; this may change in the future).
 
 ### Hot reloading
 
-The Jekyll development server supports "hot reloading" (where local changes
-will be automatically reflected in your browser without having to manually
-reload). You can activate this by sending the `--livereload` flag (`-l` for
-short) to `serve.sh`.
+The development server recognizes when files change (including static files)
+and local changes will be automatically reflected in your browser upon reload.
 
 ### Local Installation
 
 It is possible to run the development server locally also. The general gist of
 how to do so correctly is:
 
-- Install [rbenv](https://github.com/rbenv/rbenv).
-- Use rbenv to install an appropriate version of Ruby.
-- `gem install bundler`
-- `bundle install`
-
-Once this is done, you can run `bundle exec jekyll serve` to run the
-development server (as above, include `--livereload` to get automatic
-reloading).
-
-**Note:** The Jekyll default setup will write the static site in-place to the
-`_site` subdirectory. (The Docker image redirects this to an arbitrary spot in
-the image so as not to pollute the local disk.)
+- Install Python 3.8 if you do not already have it (direct install is fine, but
+  [pyenv][5] is probably the best way if you have other Python projects).
+- Create a Python 3.8 [venv][6]. Once it is created, activate it in your shell
+  (`source path/to/venv/bin/activate`).
+- `pip install git+https://github.com/aip-dev/site-generator.git`
+- `aip-site-serve .`
 
 ## Contributor License Agreement
 
@@ -84,6 +74,8 @@ to ensure a consistent style throughout our source. You can add prettier as a
 plugin in most development environments.
 
 [1]: https://pages.github.com/
-[2]: https://jekyllrb.com/
+[2]: https://github.com/aip-dev/site-generator
 [3]: https://docker.com/
 [4]: https://prettier.io/
+[5]: https://github.com/pyenv/pyenv
+[6]: https://docs.python.org/3/library/venv.html

Dockerfile

@@ -1,31 +1,23 @@
-FROM ruby:2.6-alpine
+FROM python:3.8-alpine
 
-# Copy the existing code into the Docker image.
-#
-# This will copy everything *at build time* (not at runtime), so it is
-# still important to use `--mount` to get a reasonable development loop.
-# This makes the image work for both purposes, though.
-COPY . /code/
+# Define the working directory.
+# Note: There is no code here; it is pulled from the repository by mounting
+# the directory (see `serve.sh`).
 WORKDIR /code/
 
-# Install bundler and gems for this project.
-RUN echo "gem: --no-ri --no-rdoc" > ~/.gemrc && \
-  apk add --no-cache alpine-sdk && \
-  gem update --system && \
-  gem install bundler && \
-  bundle install && \
-  apk del --no-cache alpine-sdk && \
-  rm ~/.gemrc
+# Install Python packages for this project.
+COPY requirements.txt /code/requirements.txt
+RUN apk add git && \
+  pip install -r requirements.txt && \
+  apk del git
 
-# Install git. (Jekyll expects it.)
-RUN apk add --no-cache git
+# Set environment variables.
+ENV FLASK_ENV development
 
 # Expose appropriate ports.
 EXPOSE 4000
 EXPOSE 35729
 
-# Run Jekyll's dev server.
-# Reminder: Use -p with `docker run` to publish ports.
-ENTRYPOINT ["bundle", "exec", "jekyll", "serve", \
-  "--destination", "/site", \
-  "--host", "0.0.0.0"]
+# Run the development server.
+# Reminder: Use -p with `docker run` to publish ports (see `serve.sh`).
+ENTRYPOINT ["aip-site-serve", "."]