This post is part of the Elixir Setup Series, covering essential tools and practices for Elixir projects.

We should all make documentation a priority for our projects. In Elixir, the preferred tool for generating documentation is ExDoc, which outputs a Jekyll-compatible static website supported by many platforms.

Code

Documentation

Update Mix

To get started, add the ex_doc, earmark, and makeup_elixir packages to your mix.exs file dependencies:

defp deps do
  [
    {:ex_doc, "~> 0.34", only: [:dev, :docs], runtime: false},
    {:earmark, "~> 1.4", only: [:dev, :docs], runtime: false},
    {:makeup_elixir, "~> 0.16", only: [:dev, :docs], runtime: false}
  ]
end

These dependencies will only run in the :dev or :docs environments. You’ll need to create a docs environment configuration in your config directory.

Add a Docs Environment

Create a new file named config/docs.exs:

import Config

To ensure your documentation is always up-to-date and automatically published, use GitHub Actions to generate and deploy your documentation to GitHub Pages whenever changes are pushed to the main branch.

Add a GitHub Action Workflow

Create a new file named .github/workflows/publish_docs.yml:

name: Publish Docs

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    env:
      MIX_ENV: docs
    steps:
    - uses: actions/checkout@v4

    - name: Set up Erlang and Elixir
      uses: erlef/setup-beam@v1
      with:
        elixir-version: '1.16'
        otp-version: '26.0'

    - name: Install Hex and Rebar
      run: |
        mix local.hex --force
        mix local.rebar --force

    - name: Install Dependencies
      run: mix deps.get

    - name: Generate Documentation
      run: mix docs

    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: $
        publish_dir: ./doc

Configuring Repository Permissions for GitHub Actions

The GitHub Action workflow needs permission to read and write.

  1. Navigate to Repository Settings:
    • Go to your GitHub repository.
    • Click on the Settings tab.
  2. Access Actions Settings:
    • In the left sidebar, click on Actions.
  3. Set Workflow Permissions:
    • Scroll down to the Workflow permissions section.
    • Select the option Read and write permissions. This will grant the workflow the necessary permissions to read from and write to the repository.

Deploying to GitHub Pages

To deploy your documentation to GitHub Pages, you need to configure the source branch:

  1. Navigate to Repository Settings:
    • Go to your GitHub repository.
    • Click on the Settings tab.
  2. Access Pages Settings:
    • In the left sidebar, click on Pages.
  3. Set the Source Branch:
    • Scroll down to the Source section.
    • Change the branch to gh-pages.

This change should retrigger the action on the correct branch. Once completed, the top of the Pages section should show that the website is deployed along with the URL.