This Site¶

This website is currently (20190922) constructed as follows:

Content written in ReST.
Generated by sphinx
Themed by sphinx-material
Served by flask
Bundled in a docker image
Brought to you by Google Cloud Run

The following describes the various compenents required to “operate” the site. Hopefully this site is self-documenting enough. Good luck, future me.

The Root Makefile¶

Tip

tl;dr: If it’s been a while just take a look at the root Makefile before doing anything.

The Makefile found under the project root is intended to simply your life. (As any Makefile should.) Currently (20190922) the constituent targets are:

all: Default target. Simply requires the pages target. I.e this just build the docs - that is, the content - and moves that generated content into the appropriate location of the application’s static files.
docs: Use sphinx to build the site html files from the source rst files.

Note

This target won’t update the content served by the site, this will update/generate the html content in docs/build/html. To generate new content and update what get’s served (say, to see changes in when using the flask dev server), see the pages target.

pages

Sync andrewrosss_dev/static/pages/ with the content in docs/build/html after generating new docs via the docs target.

dev-server

Start serving the Flask application using gunicorn. Uses a single worker and 2 threads.

dist

Create a new distribution of the website source. Specifically, this just runs:

python setup.py sdist bdist_wheel

upload

Upload the distributions under dist/ using twine. Specifically, this runs:

python3 -m twine upload dist/*

version

Echo the current version string.

clean

Remove everything under andrewrosss_dev/static/pages/ and docs/build/.

Updating Content¶

Tip

tl;dr: Add new .rst content in docs/source/, run make pages from inside the root directory.

So new content needs to be added. Great, how to proceed?

The source .rst files that are expected by sphinx can be found in docs/source. As such, adding content should be as easy as adding and new/editing an existing .rst file. (And presumably editing the global toc tree …)

Once you’ve added the new content, be it a plain .rst file, or a notebook, or whatever, the next step is to generate updated html. This can be done using the Makefile provided by sphinx, however the Flask application (which serves the pages) doesn’t serve those pages directly. The files that Flask serves are the ones located in andrewrosss_dev/static/pages/.

So running something like make clean && make html from inside docs/ won’t break anything, you’re just going to have to manually copy over the generated files into the andrewrosss_dev/static/pages/ directory.

Instead of doing what I just described, what you should do is, from the project root, run make pages (or make clean && make pages to rebuild from scratch.)

The pages target in the root makefile first generates new html files using sphinx, and then rsync’s docs/build/html/ with andrewrosss_dev/static/pages/, accomplishing what was described above in one command. So, do this.

Theming¶

Tip

tl;dr: Look in docs/source/conf.py and consult sphinx-material demo site.

As of this writing this site is generate using the sphinx-material package. By far the best place to look for information how to modify the presentation of this site via this sphinx theme is to check out either the GH repo or the sphinx-material demo site. That, said for theming options, you’re probably going to want to edit docs/source/conf.py (as usual with sphinx).

The Flask Application¶

Tip

tl;dr: Look in pages.py and andrewrosss_dev/, and maybe re-read part 1 of the Flask mega-tutorial

The flask application that is used to serve the static pages is exceedingly simple. Everything flask app-related that you’d likely need will be found in the pages.py module and the andrewrosss_dev/ package. Moreover, for a “real” refresher as to what’s going on, consult the Flask mega-tutorial. The application structure (think file layout) follows almost exactly what is achieved by the end of part 1 of the mega-tutorial, the notable changes being:

microblog.py -> pages.py
app/         -> andrewrosss_dev/

Otherwise, it’s all the same.

Note that there is a .flaskenv file that enables us to call:

flask run

to start the flask dev server in debug mode, however there is also a make target

make dev-server  # from inside the root directory

which starts up a small gunicorn server with the --reload switch on, this more closely resembles what’s going on in the docker container.

The Dockerfile¶

Describe what’s going on in the Dockerfile. There’s probably going to be something make-related here as well.

Cloud Run¶

Describe what’s required to host the site using Cloud Run. Maybe a bit of documentation on what it took so set it up?

Cloudbuild¶

Describe how cloud build is used to deploy new builds of the site. Note that it’s possible that a lot of what might fit under Cloud Run, above, might actually move to this section because it would be “automated away” by cloudbuild.