README.md

Edward website

The back end of our website depends on pandoc, beautifulsoup, and sphinx. This lets us write stand-alone pages for documentation using LaTeX, with functional bibliographies. It also lets us auto-generate API documentation from the source code's docstrings.

The front end of our website depends on skeleton.css, Google Fonts, highlight.js, and KaTeX.

Editing the website

All stand-alone pages are under docs/tex. These compile to HTML pages. Our custom pandoc html template is docs/tex/template.pandoc. Our APA styling for citations is docs/tex/apa.csl.

Building the website

  • Install the dependencies
pip install pandoc pandoc-attributes pandocfilters beautifulsoup4 sphinx numpydoc ghp-import
  • You can build the website locally. Go to this docs/ directory and run
./compile.sh

The output of the compile script is a set of static HTML pages. The HTML pages use absolute filepaths. In order to view them locally, use a HTTP server such as Python's built-in SimpleHTTPServer or Node.js' http-server.

Deploying the website

  • We deploy the documentation so that it is available on this repo's Github pages (the gh-pages branch). To do this (and assuming you have push permission), go to this directory. Then run
./deploy.sh

We forward the main domain url to the Github pages url, blei-lab.github.io/edward. Following Github's guide, namely, we make a CNAME file; then we update the DNS record on the DNS provider.