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

• Depends on: log4cl

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.