DocFX 적용하기

참고 사이트

https://github.com/NormandErwan/DocFxForUnity

GitHub - NormandErwan/DocFxForUnity: DocFX usage example for Unity projects

 

기본 유니티 프로젝트를 만들어서 진행했습니다.

 

.NET 설치

6.0 이상으로 설치해야 한다. https://dotnet.microsoft.com/ko-kr/download

cmd에 아래 명령어를 입력하면 설치된 버전을 알 수 있다. 나는 7.0.203 버전이었다.

dotnet --version

 

DocFX 설치

dotnet을 이용해서 최신 docfx를 설치한다. cmd에 명령어를 입력하고 한 20초 정도 기다리니까 설치가 완료됐다.

dotnet tool install -g docfx

 

DocFX 초기화

깔끔하게 정리하기 위해서 Documentation 폴더를 만든다. 만든 폴더로 이동해서 docfx를 초기화해준다. 초기화에 필요한 몇가지 질문을 하는데 엔터 꾸욱 누르면 된다. -y를 붙이면 자동으로 모두 yes를 답한다.

mkdir Documentation
cd Documentation

docfx init -y

DocFX 실행

docfx.json파일의 세팅 값을 이용해서 문서화시키는 작업이다. --serve를 입력하면 로컬웹서버에 자동으로 올려준다.

docfx docfx.json --serve

 

신기해서 이것저것 클릭해보면 docs 탭은 켜지는데 api 탭은 켜지지 않는다. api 탭은 소스 코드를 돌면서 문서화해야 하는데, 예제 소스 코드가 없어서 그렇다. 참고 사이트에 있는 예제 소스 코드가 잘 만들어져있어서 가져왔다.

 

설정 파일 수정

docfx.json을 프로젝트에 맞게 수정해보자. 기본으로 만들어진 docfx.json 파일은 아래와 같다.

{
  "metadata": [
    {
      "src": [
        {
          "src": "../src",
          "files": [
            "**/*.csproj"
          ]
        }
      ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "**/*.{md,yml}"
        ],
        "exclude": [
          "_site/**"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "output": "_site",
    "template": [
      "default",
      "modern"
    ],
    "globalMetadata": {
      "_appName": "",
      "_appTitle": "",
      "_enableSearch": true,
      "pdf": true
    }
  }
}

 

필요한 거만 남겨보자.

src 경로(../Assets)의  파일(**.cs)이 문서화가 된다.

_enableSearch를 켜면 문서 페이지에서 우측 상단에 검색 기능이 활성화된다.

{
  "metadata": [
    {
      "src": [
        {
          "src": "../Assets",
          "files": [
            "**.cs"
          ]
        }
      ],
      "dest": "api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "toc.yml",
          "index.md"
        ]
      },
      {
        "src": "api",
        "files": [
          "*.yml"
        ],
        "dest": "api"
      },
      {
        "src": "docs",
        "files": [
          "toc.yml",
          "*.md"
        ],
        "dest": "docs"
      }
    ],
    "globalMetadata": {
      "_appName": "Pukui",
      "_appTitle": "Pukui",
      "_enableSearch": true
    },
    "dest": "_site"
  }
}

 

그리고 DocFX를 실행하면 엄청난 에러가 뜬다. Unity의 네임스페이스를 못 찾는다.

error: E:/DocFXTest/Assets/Player.cs(2,7): error CS0246: The type or namespace name 'UnityEngine' could not be found (are
you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Readme.cs(2,7): error CS0246: The type or namespace name 'UnityEngine'
could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(3,7): error CS0246: The type or namespace name
'UnityEngine' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(4,7): error CS0246: The type or namespace name
'UnityEditor' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Readme.cs(4,23): error CS0246: The type or namespace name
'ScriptableObject' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/Player.cs(9,27): error CS0246: The type or namespace name 'MonoBehaviour' could not be found
(are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(11,29): error CS0246: The type or namespace name
'Editor' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(9,2): error CS0246: The type or namespace name
'CustomEditorAttribute' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(9,2): error CS0246: The type or namespace name
'CustomEditor' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(10,2): error CS0246: The type or namespace name
'InitializeOnLoadAttribute' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(10,2): error CS0246: The type or namespace name
'InitializeOnLoad' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Readme.cs(6,12): error CS0246: The type or namespace name 'Texture2D' couldnot be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(159,5): error CS0246: The type or namespace name
'GUIStyle' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(165,5): error CS0246: The type or namespace name
'GUIStyle' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(167,5): error CS0246: The type or namespace name
'GUIStyle' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(173,5): error CS0246: The type or namespace name
'GUIStyle' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(175,5): error CS0246: The type or namespace name
'GUIStyle' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(181,5): error CS0246: The type or namespace name
'GUIStyle' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(183,5): error CS0246: The type or namespace name
'GUIStyle' could not be found (are you missing a using directive or an assembly reference?)
error: E:/DocFXTest/Assets/TutorialInfo/Scripts/Editor/ReadmeEditor.cs(189,5): error CS0246: The type or namespace name
'GUIStyle' could not be found (are you missing a using directive or an assembly reference?)

 

버그) 네임스페이스 못 찾음

docfx 버전 문제이다.

https://github.com/NormandErwan/DocFxForUnity/issues/9

Unable to use DocFx on Unity · Issue #9 · NormandErwan/DocFxForUnity

2.61.0 버전으로 다시 깔아주자. 2.61.0 버전 위로는 네임스페이스 인식을 못한다. (하나씩 다 설치해봤다...)

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

다시 실행하면 잘 된다.

docfx docfx.json --serve

 

한글이 깨진다면, 소스 코드 파일을 UTF-8로 바꾸자.

결과 화면

와~~ 잘된다~~