[Github] 문서화를 위한 action (Doxygen)

1. 문서화

 

기본적으로 README를 하나하나 사람이 직접 만드는 것은 생각보다도 복잡하고 많은 시간과 노력을 필요로 한다.

 

스크립트의 양이 많고 복잡하기 때문이다.

 

또한 아주 상세하게 작성된 설명은 사실상 코드를 직접 보는 것과 차이가 없을 수 있다. (고도로 발단된 설명은 코드와 다를 바 없다.)

 

차라리 코드에 대한 최소한의 설명을 주석으로 추가하는 것이 올바를 수 있다.

 

이에 정해진 규칙에 따라서 작성된 주석을 자동으로 문서화하는 프로그램을 사용할 수도 있다.

 

3줄 요약

• 닥치고 md를 작성하는 짓은 멍청하다. → 이럴 바에는 그냥 코드를 보고 이해하는 것이 더 올바르다.
• 그럼에도 코드를 보고서 쉽게 파악하기 동작 원리는 주석으로 추가하는 것이 옳다.
• 필요하다면 최소한의 클래스와 메서드만 자동으로 문서화하는 것이 옳다.

 

---

2. 방법

 

ChatGPT 왈

Unity 프로젝트를 자동화하는 방법은 여러 가지가 있습니다. 이런 방법들 중 일부는 일반적인 프로그래밍 프로젝트에 사용되는 방법들이며, 일부는 Unity에 특화된 방법들입니다.

1. 주석문(Comments): 이는 가장 기본적인 방법으로, 코드에 주석을 달아서 각 기능이 어떤 역할을 하는지, 어떻게 사용되는지 등을 설명합니다.

2. 코드 문서화 도구: Doxygen, Sandcastle, DocFX 등과 같은 도구를 사용하면, 코드에 있는 주석을 추출하여 HTML, PDF 등의 형식으로 출력해 줍니다. 이렇게 하면 코드를 읽지 않고도 각 클래스, 함수 등이 어떤 역할을 하는지 확인할 수 있습니다.

3. 자동화된 테스트 도구: Unit Test를 작성하고, 이를 자동으로 실행해 주는 도구를 사용하면, 코드가 정상적으로 동작하는지 확인할 수 있습니다. 이런 테스트 코드는 문서의 일종으로도 볼 수 있습니다. Unity에서는 NUnit 프레임워크를 이용해 유닛 테스트를 작성할 수 있습니다.

4. Unity 특화 도구: Unity는 Inspector 창을 사용해서 컴포넌트의 속성을 조절할 수 있습니다. 이런 속성에 대한 설명을 Tooltip을 통해 제공하면, 코드를 읽지 않고도 어떤 역할을 하는지 알 수 있습니다.

5. 버전 관리 시스템: Git 같은 버전 관리 시스템은 코드의 변화를 추적하는 데 매우 유용합니다. 각 변경 사항에 대한 설명을 커밋 메시지로 남겨두면, 이전 코드와의 차이점, 그리고 이 변경 사항이 왜 필요했는지 알 수 있습니다.

위 방법들을 적절히 조합하면 Unity 프로젝트의 문서화를 자동화하고, 프로젝트의 이해를 돕는데 많은 도움이 됩니다.

아래 표는 Doxygen, Sandcastle, DocFX에 대한 간략한 비교입니다.

 

 

(출처 : GPT4.0)

 

2번의 코드 문서화 도구들 중 Doxygen을 활용해서 코드를 문서화를 시도해 보겠다. (시간 있으면 DocFX도 시도해 보겠다.)

 

---

3. Doxygen action

 

로컬 PC에 Doxygen을 설치해서 실행해도 좋지만 이왕이면 github action을 사용해서 자동화해보자.

 

Doxygen GitHub Pages Deploy Action - GitHub Marketplace

 

 

...

Run doxygen Doxyfile
error: configuration file Doxyfile not found!

...

 

File ./Doxyfile could not be found

 

Doxygen 실행에 앞서 configuration file인 Doxyfile이 필요함.

 

---

4. Workflow file 수정

 

Doxygen을 설치하고 configuration file을 생성해야 한다.

 

setting을 먼저 바꾸고 진행하자.

 

Doxyfile을 만드는 workflow file이다. (로컬 컴퓨터에 설치하고 지우기 귀찮아서 action으로 처리했다.)

 

Doxyfile에 생성되면 해당 action은 삭제한다. (최초 1회만 실행)

 

name: Doxygen Install, Generate, and Commit

on:
  workflow_dispatch:

jobs:
  doxygen:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Install Doxygen
        run: sudo apt-get install doxygen

      - name: Generate Doxyfile
        run: doxygen -g

      - name: list Doxyfile
        run: pwd && ls -al

      - name: Commit and push if changes
        run: |
          git add .
          git config --global user.email "you@example.com"
          git config --global user.name "Your Name"
          git commit -m "Generate Doxyfile" && git push

 

 

생성된 Doxyfile을 열어서 몇 가지 주요 설정을 수정한다.

• DOXYFILE_ENCODING = EUC-KR로 변경.
• OUTPUT_LANGUAGE = Korean로 변경.
• INPUT_ENCODING = EUC_KR로 변경.
• PROJECT_NAME 수정하기.
• GENERATE_HTML로 출력 형식을 설정하기.
• EXTRACT Option 선택하기 (all, private, static, … 등 포함할 범위)
• INPUT 설정하기.
• FILE_PATTERNS 설정하기.
• RECURSIVE = YES로 변경.
• GENERATE_TREEVIEW 선택.

등등 친절하게 설명해 놓았으니 천천히 읽어보고 선택하면 된다.

 

아래 worlflow file을 추가한다.

name: Doxygen GitHub Pages Deploy Action

on:
  pull_request:
    types: [closed]
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    if: github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - run: pwd && ls -al
      - uses: DenverCoder1/doxygen-github-pages-action@v1.3.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages
          folder: docs/html
          config_file: Doxyfile

설정에 따라 문서화를 진행한 후에 GitHub Pages에 배포하는 작업을 수행한다.

 

💡 Check out은 무엇이며 왜 수행해야 하는가?

"Check out"은 Git 용어로, 특정 브랜치나 커밋의 상태를 로컬 환경에 복제하는 작업을 의미합니다.

GitHub Actions 워크플로우에서는 "actions/checkout" 액션을 사용하여 이 작업을 수행하며, 이를 통해 워크플로우가 실행되는 가상 환경에 코드 저장소의 내용이 복제됩니다.

이 단계는 코드를 컴파일하거나 테스트를 실행하고, 여기서는 Doxygen 문서를 생성하기 위해 필요합니다.

 

💡 DoxyFile은 무엇이며 어떤 역할을 수행하는가?

Doxyfile은 Doxygen을 위한 설정 파일입니다.

이 파일을 통해 Doxygen이 어떤 소스 코드 파일을 분석할지, 어떤 형태로 문서를 생성할지 등의 세부 설정을 지정할 수 있습니다.

 

💡 이 action을 정상적으로 수행하려면 GitHub Pages를 우선적으로 만들어야 하는가?

이 액션을 정상적으로 수행하려면 gh-pages 브랜치가 있어야 합니다.

GitHub Pages는 이 브랜치를 기본으로 사용하여 웹사이트를 호스팅 합니다. 만약 브랜치가 없다면, 이 액션은 gh-pages 브랜치를 새로 생성하고 사용합니다.

 

💡 이 action을 정상적으로 수행하려면 GitHub token이 우선적으로 발급되어 있어야 하는가? 만약 그렇다면 organization에서는 GitHub token을 어떻게 발급하는가?

GitHub Actions은 기본적으로 secrets.GITHUB_TOKEN을 제공합니다.

이 토큰은 GitHub이 자동으로 생성하고 관리하는데, 액션을 실행하는 레포지토리에 대한 권한을 부여합니다.

이를 통해 워크플로우는 레포지토리에 push 하거나 pull request를 생성하는 등의 작업을 수행할 수 있습니다.

이 토큰은 별도로 발급받을 필요가 없습니다.

그러나 추가적인 권한이 필요한 경우, 또는 조직 레포지토리에서 작업을 수행할 경우에는 별도의 개인 액세스 토큰(PAT)을 발급받아 사용할 수 있습니다.

이는 GitHub 웹사이트의 설정 메뉴에서 발급받을 수 있습니다.

발급받은 토큰은 액션에서 사용하기 위해 'Secrets'에 등록해야 합니다.

조직 레포지토리에서는 조직 관리자가 PAT를 생성하고, 조직 레벨의 'Secrets'에 등록할 수 있습니다.

 

---

error 1

 

Run touch docs/html/.nojekyll
touch: cannot touch 'docs/html/.nojekyll': No such file or directory
Error: Process completed with exit code 1.

docs/html 디렉터리를 찾지 못해서 오류가 발생했다.

 

mkdir -p docs/html

docs/html 디렉터리를 생성해 주고 다시 실행한다.

 

github에서는 텅 빈 디렉터리는 자동으로 삭제하니 .tmp와 같은 빈 파일을 넣자.

 

---

error 2

 

...
There is nothing to commit. Exiting early… 📭

 

정상적으로 action이 실행되었지만 위와 같은 로그가 출력되면서 아무런 변화가 없는 경우.

 

Doxygen의 실행 결과 생성되는 결과물이 workflow file에서 입력한 folder 경로 (여기선 docs/html) 아래에 output 되지 않으면 발생한다.

 

 

Doxyfile의 OUTPUT_DIRECTORY를 수정한다.

 

action의 workflow file에서 folder의 value로 입력한 경로를 동일하게 입력한다.

 

---

error 3

 

 

생성된 index.html이 위치한 디렉터리를 ‘Select folder’로 선택할 수 없는 경우.

 

Set subdirectory as website root on Github Pages

 

source를 Github Actions로 변경 → Configure 클릭 → path 수정

 

---

error 4

 

특정 workflow가 끝난 후에 이어서 실행하도록 하는 방법.

 

Doxygen GitHub Pages Deploy Action 이후에 Deploy static content to Pages를 실행시키고 싶을 때.

 

on:
  workflow_run:
    workflows: ["Doxygen GitHub Pages Deploy Action"]
    types:
      - completed

 

---

error 5

 

Run actions/upload-pages-artifact@v1
Run tar \
tar: html: Cannot open: No such file or directory

./html을 못 찾는 경우.

 

Deploy static content to Pages workflow가 main 브랜치에서 동작하기 때문에 checkout에 gh-pages 브랜치를 checkout 하도록 별도로 지정하지 않으면 default 브랜치인 main 브랜치를 checkout함.

 

이때 main 브랜치에는 ./html 디렉터리가 없어서 오류가 발생함.

 

gh-pages 브랜치를 checkout하도록 수정해야 함.

 

 

---

5. 두둥 탁

 

 

name: Doxygen GitHub Pages Deploy Action

on:
  pull_request:
    types: [closed]
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    if: github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - run: pwd && ls -al
      - uses: DenverCoder1/doxygen-github-pages-action@v1.3.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: gh-pages
          folder: docs/html
          config_file: Doxyfile

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  workflow_run:
    workflows: ["Doxygen GitHub Pages Deploy Action"]
    types:
      - completed

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          ref: gh-pages
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload entire repository
          path: './html'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

 

---

6. Doxygen tag

 

 

/// @breif change breif test
public class SampleClass
{
    /**
    * @breif This is a Doxygen comment for the SampleClass.
    */
    public SampleClass()
    {
    }

    /**
    * @brief please do something!!
    * @param param1 This is a parameter.
    * @return int Returns an integer.
    */
    public int DoSomething(int param1)
    {
        return param1;
    }
}

 

---

7. Marhen 문서화

 

Marhen: 메인 페이지

 

---