DotNet
프로젝트 관리
주석문서화
Git 연동

Git 연동

GitHub 리포지토리 설정

리포지토리 생성

GitHub에서 새로운 리포지토리를 생성합니다. 리포지토리를 공개 또는 비공개로 설정할 수 있습니다.

프로젝트 파일 초기화

생성한 DocFX 프로젝트 파일을 GitHub 리포지토리에 업로드합니다. 이를 위해 명령줄에서 Git을 사용하여 파일을 커밋하고 푸시할 수 있습니다.

# 리포지토리 초기화
git init
git add .
git commit -m "Initial commit"

관리 항목 정리 

# DocFX 빌드 결과물
_site/
# DotNet 빌드 결과물
bin/
obj/
# 사용자별 설정 파일
.vscode/
.idea/
*.user
*.suo
# OS별 파일
.DS_Store
Thumbs.db
# 기타 불필요한 파일
*.log
*.tmp

푸시 

git remote add origin https://github.com/YOUR_USERNAME/CLib.git
git push -u origin master

DocFX 설정 및 문서 작성

GitHub Actions 를 통한 CI/CD 설정

GitHub Pages 설정

GitHub Pages 활성화

먼저, GitHub Pages를 활성화합니다.

  1. GitHub 리포지토리 페이지로 이동: GitHub에서 해당 리포지토리로 이동합니다.
  2. Settings: 상단 메뉴에서 Settings를 클릭합니다.
  3. Pages: 좌측 메뉴에서 Pages를 선택합니다.4.
  4. Source: Source 섹션에서 배포할 브랜치를 선택합니다. 일반적으로 gh-pages 브랜치를 사용합니다.
    • Branch: gh-pages 선택
    • Folder: /root 선택
  5. Save: Save 버튼을 클릭하여 설정을 저장합니다.

3. GitHub Personal Access Token 설정

GitHub Pages에 배포하려면 Personal Access Token이 필요합니다.

  1. 토큰 생성:

    • GitHub 사용자 설정(Settings)으로 이동합니다.
    • Developer settings -> Personal access tokens로 이동합니다.
    • Generate new token을 클릭하고, repo 권한을 선택하여 새로운 토큰을 생성합니다.

  2. GitHub 리포지토리로 이동:

    • 리포지토리의 Settings -> Secrets and variables -> Actions로 이동합니다.
    • New repository secret을 클릭합니다.
    • Name에 GH_TOKEN, Value에 생성한 Personal Access Token을 입력합니다.

GitHub Actions 설정 파일 생성

  • 프로젝트의 루트 디렉토리에 .github/workflows 디렉토리를 만들고, main.yml 파일을 생성합니다.
mkdir -p .github/workflows
echo. > .github/workflows/main.yml
  • main.yml 파일에 다음 내용을 추가합니다.
name: Build and Deploy DocFX Documentation
on:
  push:
    branches:
      - master
    paths:
      - '**.csproj'
      - 'docs/**'
      - 'articles/**'
      - 'toc.yml'
      - '*.md'
      - '.github/workflows/main.yml'
      - 'docfx.json'
jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Setup .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: '8.0.x'
    
    - name: Install DocFX
      run: dotnet tool install -g docfx
    
    - name: Build documentation
      run: docfx build -o _site
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./_site

4. 파일 커밋 및 푸시

이제 모든 설정이 완료되었으므로, 파일을 커밋하고 GitHub에 푸시합니다.

git add .
git commit -m "Set up DocFX and GitHub Actions"
git push origin master

master 브랜치와 gh-pages 브랜치의 관계

설정된 워크플로우에 따라 master 브랜치에 푸시할 때마다 GitHub Actions가 자동으로 실행되어 문서를 빌드하고, 그 결과를 gh-pages 브랜치에 커밋하여 배포하게 됩니다. 이렇게 하면 master 브랜치의 소스 코드와 문서가 업데이트될 때마다 GitHub Pages에 최신 문서가 자동으로 배포됩니다.

5. 배포 확인

푸시가 완료되면 GitHub Actions가 자동으로 실행되어 DocFX 문서를 빌드하고 gh-pages 브랜치에 배포합니다. GitHub Pages 설정에서 지정한 URL을 통해 배포된 문서를 확인할 수 있습니다. 예를 들어, 리포지토리가 https://github.com/YOUR_USERNAME/CLib일 경우, GitHub Pages URL은 https://YOUR_USERNAME.github.io/CLib/입니다.

Buy me a coffee Buy me a coffee
DocFXdocfx 관리 단위