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.
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
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
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.
We set up Ruby and install some dependencies. We build our Ruby API docs using YARD.
Finally, we invoke
yardoc to generate the documentation in the
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
- 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.
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
Once you’ve set up a little publishing pipeline for your static documentation, you can take it up a notch. For example:
/.yardoptsfile in order to clean up your Github action workflow.
bin/generate-docs) that does all of the setup and generation. Automation over documentation!
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.