Photo by matthew Feeney on Unsplash

Automated HTML docs for your project

Use GitHub Actions and Pages to publish HTML documentation from source code for your project.
Arjan van der Gaag
Arjan van der Gaag
Feb 2, 2021
Documentation

I’ve never met a developer who liked working with other people’s poorly documented code. Still, not many developers enjoy writing documentation themselves. Well-written, up-to-date and easily accessible API documentation can be great help for newcomers and veterans alike — but there is a surprising amount of friction involved in creating and maintaining such repositories.

Recent changes at GitHub have made it a lot easier to automatically publish generated documentation for your project: you can combine GitHub Actions to automatically generate HTML documentation on repository events, and publish them on a private GitHub Pages site. This helps address how to generate technical documentation and where to put it.

Building docs with GitHub Actions

We can use GitHub Actions to automate building static HTML pages from our inline API docs. Add a new workflow file in your repository, for example at .github/workflows/generate-docs.yml:

name: Build & deploy documentation
on: # 1
  push:
    branches:
      - production
jobs:
  build:
    runs-on: ubuntu-latest
    name: Update gh-pages with docs
    steps:
      - name: Checkout this repo # 2
        uses: actions/checkout@v2
      - name: Set up Ruby
        uses: actions/setup-ruby@v1
        with:
          ruby-version: "2.7"
      - name: Install required gem dependencies
        run: gem install yard --no-document
      - name: Build YARD Ruby Documentation # 3
        run: yardoc --output-dir docs
  1. We specify we want to run this workflow on every push to the production branch. In our case, that’s when we release code. That makes it a good time to update documentation.

  2. We set up Ruby and install some dependencies. We build our Ruby API docs using YARD.

  3. Finally, we invoke yardoc to generate the documentation in the ./docs directory.

To make this all work, we need one more step: we want to keep the generated files out of our main development tree. We can push them to the special gh-pages branch, which GitHub can use to publish to GitHub Pages. To do so, we use the peaceiris/actions-gh-pages action:

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: $
    publish_dir: ./docs
    publish_branch: gh-pages

Note how the secret GITHUB_TOKEN comes pre-configured on your repository, allowing you to make changes to your repository from your actions.

Publishing to GitHub Pages

Once you’ve built your project’s documentation, you need to configure your GitHub repository to publish the gh-pages branch as a GitHub Pages site. You can choose whether to restrict access to users with access to the repository or not, which is useful for private repositories.

Screenshot of the visibility options for GitHub Pages
GitHub allows access to pages to be restricted to users with repository access, making it a good fit for content you do not want to be publicly available.

Once set, GitHub will give show you the URL where you can access your new site. This site will now be automatically updated on every push to the production branch.

Next steps

Once you’ve set up a little publishing pipeline for your static documentation, you can take it up a notch. For example:

More from Floryn

Floryn

Floryn is a fast growing Dutch fintech, we provide loans to companies with the best customer experience and service, completely online. We use our own bespoke credit models built on banking data, supported by AI & Machine Learning.

© 2021 Floryn B.V.