[Docfx] 자동 문서화 툴 Docfx 시작하기

들어가며

코드 문서화는 개발자에게 있어서 중요한 요소다. 코드의 구조가 어

Docfx 시작하기

dotnet tool install -g docfx

글로벌 docfx 설치

dotnet tool uninstall -g docfx
dotnet tool install -g docfx --version 2.61.0

최신버전의 docfx를 설치했다면 삭제하고 2.61 버전으로 다운 받아야 한다.
이유는 알 수 없지만 최신버전의 Doxfx로는 Unity 문서를 작성할 수 없다. 자세한 내용은 후술 하겠다.

---

Assets/Package/Documentation~ 에서하기

폴더 구조

https://github.com/NormandErwan/DocFxForUnity 이거 따라하기

  .
  ├── Assets
+ ├── Documentation
  ├── Package
  ├── ProjectSettings
  └── README.md

프로젝트 루트 폴더에 Documentation 폴더를 놓고 안에서 Docfx 파일을 생성해 줄 것이다.

docfx init -y
docfx build 주소 --serve
docfx build --serve

기본파일 제작 및 기본 서버 시작 명령어로 https://localhost:8080 를 통해 화면을 볼 수 있다.

init시 새폴더를 생성 후 안에 데이터를 생성하는데 해당 데이터를 Documetaion으로 옮겨주자

Docfx 문서 화면

---

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

원래 DocFX에서 권장하는 폴더 구조다. 솔루션 파일인 *.sln과 기타 실행 파일을 Src 안에 다가 넣으라곤 하지만 *.sln와 기타 파일들은 루트 폴더에 있어야 하기에 우리는 Documentation를 프로젝트 루트 폴더에 넣을 것이기 때문에 우선 폴더만 구축한다.

메타데이터 설정

  "metadata": [
    {
      "src": [
        {
          "src": "../",
          "files": [
            "**/*.csproj",
            "**/*.sln"
          ]
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }

Documentation/docfx.json 파일을 열면 소스 간의 연결성을 알기 위한 메타데이터의 설정을 위한 metadata 영역이 있다. 각 항목이 무엇을 뜻하는지 설명하면

• metadata : 소스 연결을 위한 설정값
  • src : 탐색할 소스 정보
    • src : 소스를 탐색할 영역 “../” 를 작성해 루트 폴더부터 탐색한다.
    • files : 솔루션, 프로젝트 파일 와일드 카드 설정
  • dest : 만들어진 metadata 및 기타 파일을 저장할 폴더 이름

docfx.json

DocFX의 설정파일로 문서를 생성할 때 사용하는 여러가지 설정을 정의하는 json 파일이다.

{
    "build": {
      "globalMetadata": // Edit your documentation website info, see: https://dotnet.github.io/docfx/tutorial/docfx.exe_user_manual.html#322-reserved-metadata
      {
        "_appTitle": "Example Unity documentation",
        "_appFooter": "Example Unity documentation",
        "_enableSearch": true
      },
      "sitemap":
      {
        "baseUrl": "https://normanderwan.github.io/DocFxForUnity" // The URL of your documentation website
      }
  }

필터 작성하기

https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis
이거에 따르면 Docfx는 오직 public타입 메서드만 불러올 수 있다.
프라이빗도? [EditorBrowsableAttribute] 어트리뷰트를 이용하면 포함 할 수 있다.

UID 기반 필터

모든 아이템은 UID를 가지고 다시 정규표현식을 이용하지 않도록 필터링할 UID가 있다. 예제에서는 uidRegex를 사용하여 uid가 Microsoft.DevDiv로 시작하지만 Microsoft.DevDiv.SpecialCase로 시작하지 않는 모든 API를 제외합니다.

apiRules:
- include:
    uidRegex: ^Microsoft\.DevDiv\.SpecialCase
- exclude:
    uidRegex: ^Microsoft\.DevDiv

특정 네임스페이스 제외법

{
  "metadata": {
    "src": [{
      "files": ["**/bin/Release/**.dll"],
      "src": "../"
    }],
    "dest": "api",
    "filter": "filterConfig.yml" // <-- Path to custom filter config
  }
}

먼저 filterConfig.yml 파일을 사용하는 것을 설정한다.

Edit Documentation/filterConfig.yml:
apiRules:

• include: # The namespaces to generate
  uidRegex: ^Your.Namespace1
  type: Namespace
• include:
  uidRegex: ^Your.Namespace2
  type: Namespace
• exclude:
  uidRegex: .* # Every other namespaces are ignored
  type: Namespace

어트리뷰트 필터

This example excludes all APIs which have AttributeUsageAttribute set to System.AttributeTargets.Class and the Inherited argument set to true:

apiRules:

• exclude:
  hasAttribute:
  uid: System.AttributeUsageAttribute
  ctorArguments:
  • System.AttributeTargets.Class
    ctorNamedArguments:
    Inherited: “true”

추천 코드 작성법

XML태그와 C# 문서 코멘트

C#은 XML을 통해 주석을 단다 ㅇ

필터사용하기

filterConfig.yml

apiRules:
- include: # The namespaces to generate
    uidRegex: GraphNode
    type: Namespace
- exclude:
    uidRegex: .* # Every other namespaces are ignored
    type: Namespace

https://dotnet.github.io/docfx/index.html https://github.com/NormandErwan/DocFxForUnity/issues/9 https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#filter-apis