GH-PAGES¶

GH-PAGES ASDF System Details

• Description: A helper to update gh-pages branch with documentation on your library.

• Licence: Unlicense

• Author: Alexander Artemenko

• Homepage: https://40ants.com/gh-pages/

• Source control: GIT

This utility is successor of https://github.com/40ants/update-gh-pages. Fully rewritten to be more maintainable and modular.

It can be used as a standalone script or from the Common Lisp system.

How does it work

This script can be run inside a CI pipeline to upload HTML documentation into a separate git branch, used to serve static site on GitHub Pages. Also, you can run it manually on localhost.

The script does a few steps:

• it determines in which environment it is running

• what is the proper upstream Git repositor

• then set up a gh-pages branch

• uploads content of the given directory, as the content of the gh-pages branch.

CI Support

Currently gh-pages supports following CI systems:

• GitHub Actions

• Travis (not tested yet)

Also, you can run it from you own machine.

To use the utility on CI, make sure there is a github token in the GITHUB_TOKEN environment variable. Don't commit it into the repository, usually CI provides a way to set such secrets in a secure way. Inside GitHub actions this token should be already defined.

To learn, how to add support for other CI systems, read protocol.lisp and github.lisp as the reference implementation.

Untitled ¶

To install gh-pages, use Roswell:

ros install 40ants/gh-pages

After this command, an executable file ~/.roswell/bin/gh-pages will be created.

Untitled ¶

Usage: gh-pages [-h] [OPTIONS] PATH...

  -h, --help                  Show help on this program.
  -b, --branch=STR            A branch to push to (default: gh-pages)
                              Default: gh-pages

In most cases you have to specify a path to a directory containing HTML docs and script will do the rest.