Doxygen-Autodocs on GitHub Pages

autodocs-github-pages.md

Doxygen-Generated Autodocs on GitHub Pages

General Idea

GitHub offers hosting documentation on GitHub Pages. This can be done once for each GitHub user, for each GitHub organization, for each GitHub project.

If the process for building the autodocs is already in place (as is the case for libyui), it is just a matter of generating them, moving them to the right place, and deploying them to the project's GitHub Pages.

The Magic "gh-pages" Branch

GitHub pages use a special branch named gh-pages. Put an index.html or an index.md file to a directory, commit it to that branch, and you'll get a page on the project's GitHub page. The URL is something like https://username.github.io/projectname/... plus of course the directory hierarchy where the index.html or index.md file is.

Manual Process

To generate and publish the C++ class documentation for the libyui base library in my fork, I did:

• Clone the repo and go to the checkout:

git clone -o mine git@github.com:shundhammer/libyui.git
cd libyui

• Create a fresh empty branch named gh-pages (the exact branch name is important!):

git branch | grep -q "gh-pages" && git branch -D gh-pages
git branch gh-pages
git checkout gh-pages

• Generate the autodocs:

make -C libyui -f Makefile.repo doc

The autodocs are now in ./libyui/build/doc/html.

• Move the freshly generated autodocs to the desired directory and add them to the gh-pages branch:

rm -rf api-doc
mv libyui/build/doc/html api-doc
git add api-doc/**
git commit -am "Generated API doc"
git push -f mine gh-pages:gh-pages

• Check the result at https://shundhammer.github.io/libyui/api-doc/

  or in the GitHub source code browser at https://github.com/shundhammer/libyui/tree/gh-pages .

Automation

This was implemented as a GitHub action with libyui/libyui#26: We already had a docker image from which to build libyui, so it was just a matter to add a new GitHub action that executes the above steps:

Some GitHub authentication token might be required to have push permissions in the actions.

Amazingly enough, no additional credentials were required to push to the gh-pages branch; but the Git committer needs to be identified with git config.

Disk Space / Download Size

@lslezak raised concerns that the autodocs might be quite large and thus inflate the sources when cloning the repo. This is a valid point.

We checked, and it turned out that even though the generated HTML and PNGs (for the class diagrams) consume 21 MB, in the .git directory it's compressed to only 4 MB (to a total of 29 MB at the time of this writing). And since we don't keep a history of the changes in the autodocs (we delete the existing gh-pages branch first, create a new one and force-push it), this does not accumulate over time.

Using an Orphan Branch

To further minimize disk usage, I tried to create the branch with git checkout --orphan gh-pages. But that is actually counterproductive: It does not save any disk space, but the GitHub source code browser now says something like "this branch is 1 commit ahead, 6430 commits behind master" which sounds confusing.

The reason is that such an orphaned branch now contains the new api-doc/ subdirectory with the generated autodocs, but it still also contains all the source code subdirectories (libyui/, libyui-qt/, libyui-ncurses/, ...), but the files there are now all considered brand new.

While it is possible to simply remove those subdirectories before the git commit step, this is adding an awkward and potentially dangerous step to the process; and there is little gain to outweigh that.

Force-Pushing from a Script - an Accident Waiting to Happen?

git push -f can be dangerous if done wrong. But we are using GitHub branch protection for our master branch and for the release branches (SLE-15-SP3 etc.).

Still, we want to be careful with that, of course.

Support for Older Released Versions

We want to provide this documentation also for official distro releases such as SLE-15-SP3, SLE-15-SP2, ... (how far back?) if possible.

Can we do that with GitHub pages? This seems to make it a lot more complicated, especially if we start the new gh-pages branch from scratch each time. [Research needed]

Pushing from a GitHub Action

See https://stackoverflow.com/questions/57921401/push-to-origin-from-github-action/58393457#58393457

Useful bookmarks

• GitHub environment variables: https://docs.github.com/en/actions/reference/environment-variables

• GitHub pages action: https://github.com/marketplace/actions/github-pages-action

The exact YML file for the GitHub action definition:

https://github.com/libyui/libyui/blob/master/.github/workflows/publish-api-doc.yml

# This generates Doxygen autodocs for the C++ API (for the libyui base lib)
# and pushes them to the "gh-pages" branch which publishes them
# to the project's GitHub pages at https://libyui.github.io/libyui/api-doc/
#
# See also
#
#   https://gist.github.com/shundhammer/ed359db0d9329d4db551528256060d2a
#
# GitHub actions syntax:
#   https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions

name: publish-api-doc

# Trigger this when a pull request is merged (which implies pushing to master).
on:
  push:
    branches:
      - master

jobs:
  api-doc:
    runs-on: ubuntu-latest
    container: registry.opensuse.org/devel/libraries/libyui/containers/libyui-devel:latest

    steps:

    - name: Git Checkout
      uses: actions/checkout@v2

    - name: Create clean gh-pages branch
      run:  git checkout -b gh-pages

    - name: Generate autodocs for libyui base lib
      run:  make -C libyui -f Makefile.repo doc

    - name: Move generated autodocs to target directory
      run:  mv libyui/build/doc/html api-doc

    - name: Add generated autodocs to Git repo in the gh-pages branch
      run:  |
        git config --global user.email "libyui-github-bot@suse.com"
        git config --global user.name  "$GITHUB_WORKFLOW GitHub action"
        git add api-doc
        git commit -am "Generated API doc"

    - name: Publish autodocs as GitHub pages
      run:  git push -f origin gh-pages:gh-pages

    - name: Result URLs
      run:  |
        REPO_OWNER=$(echo $GITHUB_REPOSITORY | cut -d '/' -f 1)
        REPO_NAME=$(echo $GITHUB_REPOSITORY | cut -d '/' -f 2)
        echo "Formatted API docs:  https://$REPO_OWNER.github.io/$REPO_NAME/api-doc"
        echo ""
        echo "GitHub pages branch: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/tree/gh-pages" 

This will also work:

https://gist.github.com/Siddhant-K-code/05f06eaa478d11627c6b9253bc0d2996

name: Doxygen

on:
  repository_dispatch:
  push:
    branches:
      - master
      - gh-pages

# In that case do the job 'make_and_deploy_doxygen'
jobs:
  make_and_deploy_doxygen:
    runs-on: ubuntu-latest
    # which needs the following steps to be executed:
    steps:
      # 1. Checkout current branch of GitHub repository.
      - name: Checkout current branch
        uses: actions/checkout@v2
      # 2. Install doxygen and its auxiliary components.
      - name: Install doxygen and latex components
        run: sudo apt-get update; sudo apt-get install -y doxygen graphviz texlive-full
      # 3. Create the doxygen pages.
      - name: Create the doxygen
        run: |
          git clone https://github.com/metacall/core.git
          mkdir core/build && cd core/build
          cmake -DOPTION_BUILD_DOCS=ON ..
          make api-docs
      - name: Moving Files
        run: |
          mv ./core/build/docs/api-docs ./api

      # Deploy to GitHub Pages
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./