Automated HTML docs for your project

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.

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:

• Improve your API documentation by writing docs in Markdown using Kramdown, which also supports syntax highlighting.
• Generate Swagger API docs. Currently we use the Redoc NPM package to do that.
• Move all your YARD options into a /.yardopts file in order to clean up your Github action workflow.
• Provide a single hook script (e.g. bin/generate-docs) that does all of the setup and generation. Automation over documentation!
• Hook up you technical API documentation with higher-level conceptual documentation that is not necessarily tied to repository events. For example, GitHub wikis will work nicely.