[VisualStudio] Documentation - DocFx를 이용해서 솔루션 문서화하기

DocFx로 존재하는 Solution 문서화 하기

진행 중인 프로젝트 (.NET Framework 4.6 기반의 Window Forms Applicaiton Framework 구성)에서 여러 가지 다양한 구성과 기능들과 Core Function 들을 구성해서 제공하지만, 프레임워크 수준의 API 들을 문서화하는 단계를 거치지 못하고 템플릿 (Project / Item) 들과 단위 샘플 코드들과 Visual Studio 의 Intellisense 를 통해 운영하다 보니 개발자들이 API 를 통해 쉽게 처리할 수 있는 것들도 고민이나 질문 또는 찾아보는 수고를 생략하고 기존 방식대로 코드를 자체 생산해서 사용하는 의도하지 않는 문제가 발생하고 있다.

물론 정상적인 기간과 진행이 담보되면 모두 다 구성해서 반복적인 전달 교육을 통한 후에 진행을 해야 하지만, 단기에 구성해서 개발에 적용해야 하는 상황이라 개발 가이드를 통해서 개념적인 부분을 설명하고 샘플 코드 기반으로 전달 교육을 4차례나 진행했지만 개발을 진행하다 보면 이런 저런 경우와 상황이 발생하게 마련이고 이런 경우에 처리를 어떻게 해야할지를 이해하는 것에 한계가 있기 때문에 쉽게 찾아 볼 수 있는 API 문서를 Visual Studio 빌드 작업과 통합할 수 있는 툴을 검색하던 중에 DocFx 라는 오픈 소스를 발견해서 적용해 보기로 했다.

예전에도 한번 적용해 봐야지 했다가 기간과 다른 작업들에 밀려서 하지 못한 것을 이번 기회에 적용해 보도록 한다.

¶DocFx 란?

DocFx 는 마이크로소프트에서 제작한 문서화 도구로 GitHub에 공개된 오픈소스다. 문서화 도구뿐만 아니라 Jekyll, Hexo 과 같은 정적 사이트 생성 기능의 복합 제품이라고 봐야할 것 같다.

주요 처리 방식은 다음과 같다.

• Visual Studio XML Document Tool 기반 문서화
• Markdown 문법의 문서 생성
• MSBuild 연계 빌드
• Static Site 제공 (GFM - Github Flavored Markdown)

¶DocFx 설치 및 구성

¶DocFx 설치

설치하는 방법은 여러 가지가 존재한다. (DocFx 사이트의 “Getting Started” 부분을 참고) 샘플은 DocFx v2.36.1 버전을 다운로드 해서 사용하는 것으로 한다.

압축 파일로 구성되어 있으므로 다운로드한 후에 압축을 풀고 시스템 환경 변수에 DocFX 경로를 등록해 주면 된다.

¶DocFx 구성

DocFx 는 툴이기 때문에 별도의 구성이 필요없지만, 솔루션을 문서화하기 위한 기본 폴더 구조를 구성할 필요가 있다.

기본 구성은 DocFx Seed 가 있으므로 이를 이용해도 된다. 여기서는 개념적인 부분을 검토해 볼 수 있도록 직접 구성해 보도록 한다.

D:\Works\DocFXSample 과 같은 폴더를 하나 생성하고 아래와 같이 기본 폴더 구조를 만들도록 한다.

DocFXSample\
    Articles\
    Images\
    Src\
        TestLib.sln
        TestLib\

• Articles : 사이트 구성에서 Article 들 (*.md) 을 관리할 폴더 (옵션)
• Images : 이미지, 폰트 등의 리소스를 관리할 폴더 (옵션)
• Src : 작업 대상 솔루션을 위한 소스 관리 폴더 (필수)

문서화의 대상으로 사용할 TestLib.sln 파일과 TestLib 소스 폴더를 Src 폴더 밑에 복사해 놓는다.

¶DocFx 설정 파일 생성 (docfx.json)

DocFX 는 설정을 기반으로 동작하므로 위의 폴더 구성에 맞도록 설정 파일을 구성해 주면 된다.

D:\Works\DocFXSample> docfx init

대화형으로 옵션들을 물어보는 단계들이 진행되는데 별다른 이유가 없다면 기본 값으로 진행하면 된다.

아래는 생성된 docfx.json 옵션 파일의 내용이다.

{
  "build": {
    "content": [
      {
        "files": [
          "articles/**/*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "externalReference": [],
    "dest": "_site",
    "title": "DocFx Testing",
    "template": [
      "default"
    ],
    "serve": false
  }
}

위의 파일의 내용을 대략 유추해 보면 “build” 옵션 값들을 통해서 docfx 의 출력 결과물을 처리하는 방법에 대한 옵션들인 것을 볼 수 있다. 아직은 원본 소스들에 대한 설정이 없다.

이 상태로만 실행을 해 보기 위해서는 아래와 같이 서비스 명령을 사용하면 된다.

D:\Works\DocFXSample> docfx serve

실행된 결과는 localhost:8080 으로 브라우저를 실행하면 볼 수 있다. 현재는 docfx.json 파일만 존재하므로 list of files 만 보인다.

¶DocFX 설정에 소스 부분 추가 (docfx.json)

DocFX 가 소스를 인식해서 처리할 수 있도록 metadata 정보와 build > content 정보를 구성해 주면 된다.

{
  "metadata": [
    {
      "src": [
        {
          "files": ["**/*.sln", "**/*.csproj"],
          "exclude": ["**/bin/**", "**/obj/**"],
          "src": "src"
        }
      ],
      "dest": "obj/api"
    }    
  ],
  "build": {
    "content": [
      {
        "files": ["**/*.yml"],
        "src": "obj/api",
        "dest": "api"
      }
      {
        "files": [ "articles/**/*.md", "*.md", "toc.yml" ]
      }
    ],
    "resource": [
      {
        "files": [ "images/**" ]
      }
    ],
    "externalReference": [],
    "dest": "_site",
    "title": "DocFx Testing",
    "template": [
      "default"
    ],
    "serve": false
  }
}

위의 내용의 주요 항목들은 다음과 같다.

• metadata : 소스를 연계하기 위한 설정
  • src : 소스 관련 정보
    • files : 소스 대상인 솔루션 또는 프로젝트 파일 와일드 카드 설정
    • exclude : bin/obj 같은 폴더내의 파일 제외용 와일드 카드 설정
    • src : 소스 폴더 설정
  • dest : 출력 결과물은 위치시킬 폴더 설정
• build : DocFx 빌드를 위한 설정
  • content : 컨텐츠로 사용할 설정
    • files : 소스 빌드에서 생성된 파일에 대한 와일드 카드 설정
    • src : 소스 빌드에서 생성된 출력 결과 폴더 지정
    • dest : 소스 빌드의 결과를 docfx 빌드해서 결과물을 위치시킬 폴더 지정
  • resource : 이미지와 같은 Asset 파일들의 폴더 지정
  • dest : DocFx 결과 사이트 폴더 지정

더 많은 설정들과 의미는 DocFx 문서들을 참고하도록 한다.

¶사이트 구성을 위한 파일 구성

docfx.json 파일의 build > content 부분에 설정한 것과 같이 소스 연계가 아닌 사이트 구성을 위한 파일들이 필요하다.

"files": [ "articles/**/*.md", "*.md", "toc.yml" ]

articles 폴더에 게시할 *.md 파일들도 필요하지만, 사이트 루트 폴더를 구성할 파일들도 구성하면 된다.

우선 toc.yml 파일을 루트 폴더에 아래와 같이 구성하도록 한다.

- name: Home
  href: index.md
- name: Articles
  href: articles/
- name: API Documents
  href: obj/api

위의 의미는 Site 의 Root 구성이라고 생각하면 된다. 각 name 에 따라서 분류와 연결할 경로와 파일을 지정하면 된다.

toc.yml 파일에 명시된 각 폴더 (docfx.json 파일에 지정한 내용 중에서 > build > content > 2번째 files) 에는 인덱스 역할을 담당하는 toc.md 파일과 시작을 위한 index.md 파일들을 구성해 줘야 한다.

사이트 홈의 내용을 처리할 index.md 파일은 아래와 같이 간단하게 구성해 보도록 한다.

# DocFx Simple Documents

그리고 article 폴더도 수동으로 설정하는 것이므로 연계를 위한 toc.md 파일을 아래와 같이 구성해 주도록 한다.

# [Index](index.md)

위의 toc.md 에서 링크로 설정한 index.md 파일도 articles 폴더에 생성해 주도록 한다.

# Articles Index

여기까지 구성을 했으면 기본적인 설정과 연계된 파일들에 대한 구성이 된 것이므로 실제 사이트 운영이 가능하다.

D:\Works\DocFXSample> docfx 
D:\Works\DocFXSample> docfx build
D:\Works\DocFXSample> docfx docfx.json

위의 세가지 명령 중에 아무거나 사용해도 상관없다.

빌드가 진행되면 site, obj 등의 폴더가 생긴 것을 확인할 수 있다. obj 폴더는 빌드 과정의 산출물을 관리하는 폴더이고, 실제 실행가능한 것은 site 폴더다.

구성을 제대로 했다면 별다른 오류가 없이 생성이 되었을 것이므로 아래와 같이 실행을 해 보도록 한다.

D:\Works\DocFXSample> docfx serve site

브라우저에서 localhost:8080 에서 결과를 확인할 수 있다.

Notes

Visual Studio XML 주석 문서 처리

src 폴더에 기존에 존재하는 Visual Studio 솔루션 또는 프로젝트를 넣기 전에 반드시 확인해야 하는 부분이 각 소스들에 대한 XML 주석 파일이 존재해야 한다는 것이다.

만일 미리 주석을 설정하지 않았다면 각 프로젝트마다 속성 정보에서 빌드 > 출력 > XML 문서파일 의 CheckBox 를 선택해서 주석 파일을 생성하도록 해야 한다. 이 설정이 되면 각 public / protected 메서드와 클래스들은 주석이 없다면 경고로 처리되므로 이를 기준으로 주석을 구성하도록 한다.

¶결론

아주 간단하게 DocFX 를 이용해서 기존에 생성해 놓은 솔루션을 XML 문서화 정보를 기반으로 마크다운 문서로 전환하고 정적 사이트 구성을 통해서 API 문서를 볼 수 있도록 간단한 사이트를 구성해 보았다.

기존의 SandCastle 과 같이 무겁게 느껴지고 복잡함을 제거하고 단순하게 구성할 수 있다는 의미에서 좋고, 빌드를 통해서 사이트 구성을 제공할 수 있다는 점에서 좋은 것 같다.

MSBuild Task를 통해서 연계가 되므로 MSBuild 스크립트를 잘 활용하면 빌드 자동화에도 연동해서 운영할 수 있다.