Search code examples
github-actionsgithub-pagesdoxygen

doxygen documentation deployed successfully to GitHub Pages but getting 404 page not found error

I am trying to build the Doxygen documentation and publish it to GitHub Pages. Generally, I build the static HTML and CSS files, generate them, and push them with the repository. Then, I use a custom static action to publish the files to GitHub Pages. I want to automate the build and publishing process without needing to push the static web pages along with the code. So, I modified my old GitHub Action script as follows

name: build-docs
on:
  push:
    branches: ["main"]
permissions:
  contents: write
  pages: write
  id-token: write
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install Doxygen
        run: |
          sudo apt-get update 
          sudo apt-get install -y doxygen
      - name: Install Graphviz
        run: sudo apt-get install -y graphviz
      - name: Create docs directory
        run: mkdir -p ./docs/html
      - name: Run Doxygen to generate documentation
        run: doxygen ./docs/Doxyfile
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './docs/html'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Here, everything works fine, and all build logs output successfully, but when I go through the created domain, I get a 404 error: 404 error.
This is the repository: https://github.com/wissem01chiha/tinyurdf
The Pages settings are set to deployment from GitHub Actions.

I tried changing the GitHub Pages settings from the repository settings, setting the environment, and deleting it (the repository has no secrets or environment variables—I don’t have much idea about what this does).

I also tried adding a custom run job to the workflow to inspect the generated files and download the artifact. Everything seems fine (the generated web files are correct), but the publish step fails without giving any reasonable output or error!

Solution

  • In docs/Doxyfile, OUTPUT_DIRECTORY is configured twice:

    OUTPUT_DIRECTORY        = ./       # Line 9
OUTPUT_DIRECTORY = ./docs/html     # Line 38

    See:

    Due the the last one, the output is generated under:

    docs/html/html

    and, not under:

    docs/html

    As the GitHub Pages deployment is from docs/html, there's no index.html here hence the 404 Page not found error.

    So, with the current configuration:

    Changing OUTPUT_DIRECTORY to ./docs on line 9 and removing/commenting line 38 should resolve this issue:

    OUTPUT_DIRECTORY = ./docs          # Line 9

    Also, no need to create ./docs/html directory in the workflow i.e.:

    - name: Create docs directory
  run: mkdir -p ./docs/html

    It'll automatically be created by doxygen.

    Alternatively, updating path in the workflow should also work:

    path: './docs/html/html'