Publishing Configurations#

This section documents various configurations required in QuantEcon repos along with solutions to issues we have come across in the past.

Redirects#

Redirects should be setup using sphinxext.rediraffe

The following configuration is required in _config.yml

sphinx:
  extra_extensions: [sphinxext.rediraffe]
  rediraffe_redirects:
    index_toc.md: intro.md

This will redirect an old index_toc page to new intro

Setup Cache for GitHub Actions#

Our current GitHub Actions setup adds a cache mechanism to speed up Pull Request builds.

  1. The cache.yml workflow will build the entire project when changes are made to the main branch. During this workflow a copy of the _build folder saved as a workflow artifact

  2. A PR and a publish tag will fetch the cache workflow asset and unpack the _build folder prior to running jupyter-book builds.

The _build folder includes all sphinx and jupyter-cache output so will enable full caching to prevent any unnecessary conversion to html in addition to execution

Setup for GitHub Action builds using GPU#

Currently GitHub Actions does not support instances that have access to a GPU.

For lectures that require GPU support for libraries such as jax or numpyro the preview, publish, and cache workflows will use an EC2 instance that has access to a GPU (i.e. Tesla V100).

The local workflow will request an instance to be loaded on the QuantEcon AWS account and then a custom docker container (based on nvidia containers that support GPU hardware) is used to build the lectures on the EC2 instance.

Once these computations are complete it will then return the results as an artifact or load the _build/html folder to gh-pages