C++

doxygen 사용법, github pages로 배포하기

Seonghyeon Cho

2023년 6월 26일 • 4 min read

doxygen(독시즌)은 소스코드 주석으로 문서를 만드는 프로그램이다.

설정은 Doxyfile(독시파일)로 관리가 가능하며, 옵션이 다양하지만 이번 포스트에서는 기본 설정으로 C++ 프로젝트를 github actions을 이용해 github pages에 배포하는 것까지만 해보도록 하겠다.

Doxygen 설치 및 설정

brew install doxygen

설정 추가와 테스트를 위해 로컬에 doxygen을 설치한다

# 문서 만들기
doxygen

# Doxyfile 생성
doxygen -g [configName]

설치했으면 -g 옵션으로 Doxyfile을 만들 수 있다. 옵션 뒤에 Doxyfile 이름을 지정할 수도 있다.

Doxyfile은 #으로 주석을 쓰고 KEY = VALUE 형식으로 작성돼있다.

PROJECT_NAME = "my project name"

# 폴더 설정. INPUT 폴더를 비워놓으면 current directory가 대상이 된다
INPUT =
OUTPUT_DIRECTORY = build_doc

# html만 생성하기
GENERATE_HTML  = YES
GENERATE_LATEX = NO

Doxyfile에서 프로젝트 명, input 폴더 등 필요한 옵션을 수정한다. latex output은 사용하지 않는다.

doxygen으로 문서를 만들고, build_doc/html/index.html을 열어보면 위와 같은 페이지를 확인할 수 있다.

doxygen-awesome-css

좀 이쁜 문서를 원한다면 doxygen-awesome-css를 써보자. git 서브모듈 추가와 doxyfile 수정만 하면 알아서 적용되어서 편하다.

자세한 사용법은 README에 써있다

jothepro/doxygen-awesome-css

GitHub pages 배포

doxygen로 만든 페이지는 github pages로 배포할 수 있다. 정적 페이지라 어렵지 않다

먼저 리파지토리 설정에서 Pages 빌드 소스를 GitHub Actions로 바꿔준다.

기존엔 gh-pages 브랜치를 만들고, 그 브랜치에 업데이트 내용을 계속 커밋 후 배포하는 방식을 많이 썼는데, 굳이 이력을 남길 필요가 없다면 이 방식이 괜찮다.

# .github/workflows/deploy_docs.yml
name: Deploy doxygen to Pages

on:
  push:
    branches: ["main"]

  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive

      - name: Doxygen Action
        uses: mattnotmitt/doxygen-action@edge
        with:
          doxyfile-path: "./Doxyfile"
          working-directory: "."

      - name: Add .nojekyll
        run: sudo touch ./build_doc/html/.nojekyll

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./build_doc/html

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

그 다음 .github/workflows/deploy_docs.yml 워크플로를 위처럼 구성한다.

체크아웃 후 doxygen을 돌리고, html 페이지를 artifact로 올린 다음, 그걸 github pages로 배포하는 내용이다.

main 브랜치에 푸시하거나 actions 탭에서 수동으로 돌릴 수 있다.

배포가 잘 되는 모습

예제 repo

초 간단 C++ 프로젝트로 예제를 만들었다.