Publishing Lectures

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

    ../_images/github-releases.png

  3. Click on Draft a new release

    ../_images/github-draft-new-release.png

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

    ../_images/github-new-release.png

  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)

    ../_images/github-add-release-info.png

  6. Click on Publish Release

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

../_images/github-publish-status.png

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.

    chrome lectures/_build/html/index.html

    or if you are editing in the lectures folder

    chrome _build/html/index.html

    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

Contents