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 [email protected]: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.

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: ./