DocFX 적용하기
참고 사이트
https://github.com/NormandErwan/DocFxForUnity
GitHub - NormandErwan/DocFxForUnity: DocFX usage example for Unity projects
DocFX usage example for Unity projects. Contribute to NormandErwan/DocFxForUnity development by creating an account on GitHub.
github.com
기본 유니티 프로젝트를 만들어서 진행했습니다.
.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
Hi, following your README instructions I can display some Scripting API site if I use your own repo. But if I try to make the same steps on a new project (empty for the exception of 1 .cs script) t...
github.com
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로 바꾸자.
결과 화면
와~~ 잘된다~~
