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:
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:
Workflow#
To build and publish the current main
branch you setup a GitHub release:
Use your browser and open the
repo
page on GitHub such as lecture-python.mystClick on
Releases
Click on
Draft a new release
You will see an empty
tag
field andtitle
fieldAdd a
tag
following the patternpublish-<date>
such aspublish-2021march16
and update the title such asPUBLISH: 16th March 2021
. You can leave thedescription
field blank or add a description of the changes (if needed)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#
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 consistenthtml
output.Build
HTML
files locally using jb build commandjb build lectures
or if you are editing files in the
lectures
folder you can usejb build ./
Build
IPYNB
download notebooks locally using custom buildersphinx-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
Build
PDF
book style pdf locally using thepdflatex
builderjb 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
You can preview the
HTML
by following the instructions displayed byjupyter book
and open theindex.html
file located in your_build/html
.chrome lectures/_build/html/index.html
or if you are editing in the
lectures
folderchrome _build/html/index.html
open lectures/_build/html/index.html
or if you are editing in the
lectures
folderopen _build/html/index.html
Use
ghp-import
to sync theHTML
files to thegh-pages
branch usingghp-import -n -p -f -c <domain-name> -m <MESG> _build/html
where:
-n
instructsgithub
not to build your project using Jekyll,-p
pushes the branch toorigin/gh-pages
, and-f
forces the push to the repository to ensure the transfer is made.-c
adds aCNAME
file with the custom domain settings-m
sets the commit message. Use a descriptive message such aspublish-<date>
ghp-import is a tool that will publish a directory of files such as the
_build/html/
directory into thegh-pages
branch of a repository and push them togithub
for publication. This tool willreplace
thegh-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 usingpip
:pip install ghp-import
this tool is provided in the quantecon environment
Additional details are provided in the jupyter-book documentation