DocFX
DocFX는 주로 .NET 프로젝트에서 사용되며, XML 주석을 기반으로 API 문서를 생성하는데 유용합니다. 아래 단계별로 DocFX를 설치하고, 설정하며, 문서를 생성하는 과정을 설명합니다.
DocFX 설치
Prerequisites
- .NET Core SDK (버전 3.1 이상)
- Git
설치 방법
.NET SDK 설치 먼저, .NET SDK가 설치되어 있는지 확인합니다. .NET SDK가 설치되어 있지 않다면 Microsoft의 .NET 다운로드 페이지에서 설치할 수 있습니다.
docfx 설치 .NET CLI를 이용하여
docfx를 설치하려면 다음 명령어를 실행합니다:
dotnet tool install -g docfx- 설치 후
docfx명령어를 사용할 수 있게 됩니다.
프로젝트 설정
DocFX를 사용할 솔루션 디렉토리로 이동하여 초기 설정을 진행합니다. 관리 단위 에 대해 참고하시기 바랍니다.
- DocFX 초기화:
- 솔루션 루트 디렉토리에서 다음 명령어를 실행합니다
docfx init- 이 명령어는
_docfx_project폴더를 생성하고, 기본 설정 파일(docfx.json)과 템플릿 파일들을 포함합니다. docfx init실행 과정에서 설정하는 값들은 이후docfx.json파일을 통해 수정할 수 있습니다.
PS d:\10_Proects\CLib> docfx init
This utility will walk you through creating a docfx projects.
It only covers the most common items, and tries to guess sensible defaults.
Name (mysite): CLib
Generate .NET API documentation? [y/n] (y): y
.NET projects location (src): CLib
Markdown docs location (docs): docs
Enable site search? [y/n] (y): y
Enable PDF? [y/n]: y
About to write to DL\10_Projects\CLib\docfx.json
...
Is this OK? [y/n] (y): y
Project created at d:\10_Projects\CLib프로젝트 제거
DocFX 초기화 설정을 제거하려면 몇 가지 파일과 디렉토리를 수동으로 삭제해야 합니다.
docfx.json파일docs디렉토리api및_site디렉토리- toc.yml
- index.md
docfx.json 설정
docfx.json 파일은 DocFX의 주요 설정 파일입니다. 이 파일을 열어 필요한 설정을 추가 및 수정합니다. 기본적으로 다음과 같은 구조를 가집니다.
{
"metadata": [
{
"src": [
{
"files": [
"CLib/**/*.csproj"
],
"exclude": [
"CLib_Examples/**",
"CLib_xUnit/**"
]
}
],
"dest": "api"
}
],
"build": {
"content": [
{
"files": [
"api/**.yml",
"api/index.md",
"articles/**.md",
"toc.yml",
"*.md"
],
"exclude": [
"CLib_Examples/**",
"CLib_xUnit/**"
]
},
{
"src": "docs",
"files": [
"**/*.md"
]
}
],
"resource": [
{
"files": [
"images/**"
]
}
],
"dest": "_site"
},
"globalMetadata": {
"_appTitle": "CLib Documentation",
"_disableContribution": true
},
"template": [
"default",
"statictoc"
]
}metadata 섹션
metadata 섹션은 API 메타데이터를 생성할 소스 파일의 위치를 지정합니다.
src: 소스 코드의 루트 디렉토리 (.은 현재 디렉토리를 의미)files: 메타데이터 생성을 위해 포함할 파일 패턴 (**/*.csproj는 모든 C# 프로젝트 파일을 포함)dest: 생성된 메타데이터 파일이 저장될 디렉토리 (api)
build 섹션
build 섹션은 사이트 빌드를 위한 콘텐츠 파일의 위치를 지정합니다.
content: 문서화할 콘텐츠 파일의 위치와 패턴을 지정api/**.yml,api/index.md: API 메타데이터 파일과 API 인덱스 파일 포함docs/**/*.md: 추가적인 Markdown 문서 포함toc.yml,*.md: 테이블 목록 파일과 루트 디렉토리의 Markdown 파일 포함
resource: 리소스 파일의 위치 지정 (images/**는 이미지 파일 포함)dest: 생성된 사이트가 저장될 디렉토리 (_site)
globalMetadata 섹션
globalMetadata 섹션은 전역 메타데이터를 정의합니다.
_appTitle: 생성된 문서의 제목 (CLib Documentation)_disableContribution: 기여자 정보를 비활성화 (true)
template 섹션
template 섹션은 사용할 템플릿을 지정합니다.
default: 기본 템플릿statictoc: 정적 TOC 템플릿
문서 생성
메타데이터 생성
- 프로젝트 루트 디렉토리에서 다음 명령어를 실행합니다
docfx metadata- 이 명령어는 소스 파일에서 메타데이터를 추출하여
api폴더에 저장합니다.
문서 빌드
- 메타데이터가 생성된 후, 다음 명령어를 실행하여 문서를 빌드합니다
docfx build- 이 명령어는
_site폴더에 HTML 문서를 생성합니다.
문서 확인
로컬 서버 실행
- 빌드된 문서를 로컬 서버에서 확인하려면 다음 명령어를 실행합니다
docfx serve _site- 브라우저에서
http://localhost:8080으로 접속하여 빌드된 문서를 확인합니다.
CI/CD 통합
DocFX는 CI/CD 파이프라인과 쉽게 통합할 수 있습니다. 예를 들어, GitHub Actions를 사용하여 문서를 자동으로 빌드하고 배포할 수 있습니다.
GitHub Actions 예시
name: Build and Deploy Docs
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Set up .NET Core
uses: actions/setup-dotnet@v1
with:
dotnet-version: '3.1.x'
- name: Install DocFX
run: dotnet tool install -g docfx
- name: Build Docs
run: docfx build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./_site
Buy me a coffee