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

We’re hiring full stack software engineers.

Join us remote/on-site in ’s-Hertogenbosch, The Netherlands 🇳🇱

Join us in building a fintech company that provides fast and easy access to credit for small and medium sized businesses — like a bank, but without the white collars. You’ll work on software wiring million of euros, every day, to our customers.

We’re looking for both junior and experienced software developers.

Find out more…
Ruby on Rails PostgreSQL Docker AWS React React Native

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
      - production
    runs-on: ubuntu-latest
    name: Update gh-pages with docs
      - name: Checkout this repo # 2
        uses: actions/checkout@v2
      - name: Set up Ruby
        uses: actions/setup-ruby@v1
          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
    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:

  • 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.

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.

machine-learning people culture rails online-marketing business-intelligence Documentation agile retrospectives facilitation
© 2023 Floryn B.V.