Publishing Lectures

This page provides instructions on how to update the live content that is hosted on GitHub Pages. GitHub Pages is a service provided by GitHub that acts as a host for static web sites, such as those generated by jupyter-book.

There are two publishing pathways available:

1. Build and Publish Automatically via GitHub

2. Building Locally and Push to GitHub Pages

Build and Publish Automatically via GitHub

You can now use GitHub Actions to build the main branch and publish directly to GitHub Pages by tagging a New Release as a web based workflow.

QuantEcon repositories are also setup to provide previews of the html when submitting changes either via pull request or main branch updates.

Note

The following QuantEcon projects currently support updating using this workflow:

1. lecture-python-programming.myst

2. lecture-python.myst

Workflow

To build and publish the current main branch you setup a GitHub release:

1. Use your browser and open the repo page on GitHub such as lecture-python.myst

2. Click on Releases

   

3. Click on Draft a new release

   

4. You will see an empty tag field and title field

   

5. Add a tag following the pattern publish-<date> such as publish-2021march16 and update the title such as PUBLISH: 16th March 2021. You can leave the description field blank or add a description of the changes (if needed)

   

6. Click on Publish Release

You can check the status by clicking on the orange circle:

once the status against the Build & Publish task turns green this indicates the build and publish workflow has been completed and the live site will be up to date within a couple of minutes.

Building Locally and Push to GitHub Pages

These instructions assume you are at the base level of a QuantEcon lecture repository such as lecture-python.myst

Note

QuantEcon uses the folder lectures to contain all jupyter-book documents

Workflow

1. Activate the quantecon environment using conda:

   conda activate quantecon
   

   Warning

   Your software environment may change how the site is built. It is important to use use the quantecon environment to ensure consistent html output.

2. Build HTML files locally using jb build command

   jb build lectures
   

   or if you are editing files in the lectures folder you can use

   jb build ./
   

3. Build IPYNB download notebooks locally using custom builder sphinx-tojupyter

   jb build lectures --builder=custom --custom-builder=jupyter
   

   and copy asset to _notebooks folder in _build/html

   mkdir lectures/_build/html/_notebooks
   cp lectures/_build/jupyter/*.ipynb lectures/_build/html/_notebooks
   

4. Build PDF book style pdf locally using the pdflatex builder

   jb build lectures --builder=pdflatex
   

   and copy asset to _pdf folder in _build/html

   mkdir lectures/_build/html/_pdf
   cp lectures/_build/latex/*.pdf lectures/_build/html/_pdf
   

5. You can preview the HTML by following the instructions displayed by jupyter book and open the index.html file located in your _build/html.

   Linux

   chrome lectures/_build/html/index.html
   

   or if you are editing in the lectures folder

   chrome _build/html/index.html
   

   macOS

   open lectures/_build/html/index.html
   

   or if you are editing in the lectures folder

   open _build/html/index.html
   

6. Use ghp-import to sync the HTML files to the gh-pages branch using

   ghp-import -n -p -f -c <domain-name> -m <MESG> _build/html
   

   where:

   1. -n instructs github not to build your project using Jekyll,

   2. -p pushes the branch to origin/gh-pages, and

   3. -f forces the push to the repository to ensure the transfer is made.

   4. -c adds a CNAME file with the custom domain settings

   5. -m sets the commit message. Use a descriptive message such as publish-<date>

   ghp-import is a tool that will publish a directory of files such as the _build/html/ directory into the gh-pages branch of a repository and push them to github for publication. This tool will replace the gh-pages branch with the contents of what you point at it so it should be used carefully.

   Note

   If ghp-import is not installed you can do so using pip:

   pip install ghp-import
   

   this tool is provided in the quantecon environment

Additional details are provided in the jupyter-book documentation