Libris Auto-Generate GitHub Action

Boost productivity with Libris: Automatically generate comprehensive modern documentation for your projects.

Libris

Seamlessly integrate Libris with your development workflow to guarantee your documentation remains up-to-date. Our GitHub Action automates the generation of documentation each time you push to your repository, ensuring accuracy and consistency without manual effort.

Automatic Documentation Updates: Eliminates the need for manual updates, ensuring your documentation always matches your latest codebase.
Seamless Integration: Easily integrates with your existing GitHub workflow, making it a hassle-free addition to your development process.
Consistency and Accuracy: Maintains high standards of consistency and accuracy in documentation with every code change.
Time-Saving: Frees up valuable developer time by automating repetitive tasks, allowing your team to focus on development and innovation.

Integrating our GitHub Action into Your CI/CD

To facilitate automatic documentation updates within your repository, the workflow action requires write permissions and access to the GitHub-generated GITHUB_TOKEN secret. This guide outlines the steps to seamlessly integrate this action into your workflow.

In this guide we will set up the Libris Action in combination with a GitHub Page. Once set-up, every update pushed to your repository triggers the automatic publication of your latest documentation to your GitHub Page.

Setting Up the GitHub Workflow File

Begin by creating a GitHub workflow action file named libris.yaml within the .github/workflows directory of your repository. This action automates the documentation generation process, ensuring your project's documentation remains up-to-date with every push.

Configuration Inputs:

config: Specify the relative path to your Libris configuration file, which can be either a JSON or JavaScript file.
output: Define the relative path for the output of the generated documentation. Important: The action will overwrite existing data at this location, so ensure the output path is correctly specified to avoid unintended data loss.
branch: Define a branch under which the generated documentation will be published. It is advised to create a new branch such as docs to avoid conflicting pull requests.
orphan: Define the orphan (boolean) input to enable orphan branch behaviour. When orphan has a defined value of 'true' and the specified branch from input branch does not exist, an orphan branch will be created.

.github/workflows/libris.yaml

# Libris Auto-Generate Documenation Action.
#   Seamlessly integrate Libris with your development workflow to guarantee your documentation remains up-to-date.
#   Our action automates the generation of documentation each time you push to your repository, ensuring accuracy and consistency without manual effort.

name: Libris - Generate Documentation

# Grant write permissions in order to write the generated documentation file to your repo.
permissions:
  contents: write

# Trigger on every push.
on: push

jobs:
  update-file:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      # Optionally install Node.js and dependencies.
      # This can be useful when you use a JavaScript configuration file.
      # - name: Setup Node.js
      #   uses: actions/setup-node@v4
      #   with:
      #     node-version: '20'
      # - name: Install Dependencies
      #   run: npm install @librisio/libris
      #   # run: npm ci
      
      # Generate documentation.
      - name: Libris - Generate Documentation
        uses: librisio/libris-action@main
        env:

          # Your secret github token.
          # This token is automatically generated by github.
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

          # Your Libris API Key.
          # Must manually be created under "Settings > Secrets and variables > Actions > New repository secret".
          LIBRIS_API_KEY: ${{ secrets.LIBRIS_API_KEY }}

        with:

          # The relative input path of your configuration file, may either be a JSON or JavaScript file.
          config: './docs/config.json'

          # The relative output path for the generated documentation file.
          output: './docs/index.html'

          # The branch to where the newly generated documentation file will be pushed to.
          # Leave "" to use the branch that is being pushed.
          branch: 'docs'

          # Create an orphan branch when the defined branch does not exist.
          orphan: 'true'

Adding Your Libris API Key to Repository Secrets

For the action to access the Libris API, you must provide your Libris API Key as a secret in your repository.

In your repository navigate to Settings ⇨ Secrets and variables ⇨ Actions.
Click New repository secret to add a new secret.
Name the secret LIBRIS_API_KEY and paste your Libris API Key into the value field.

For more details on obtaining your Libris API Key, consult the Libris documentation.

Optional: Enable GitHub Pages for Your Project

Elevate your project's visibility and accessibility by setting up a GitHub Pages site to host your documentation.

In your repository navigate to Settings ⇨ Pages.
Select Deploy from branch from the section Build and deployment ⇨ Source.
Select branch docs from the section Build and deployment ⇨ Branch. This branch will not show up when the GitHub action has never been triggered.
Select folder /docs from the section Build and deployment ⇨ Branch.

By configuring GitHub Pages to deploy from the docs branch and the /docs folder, you ensure that every update pushed to your repository triggers the automatic publication of your latest documentation. The GitHub Pages site will seamlessly update following the completion of the GitHub Action, presenting your project's documentation in a professional, accessible format.