소개
DocFx Companion Tools는 DocFX 기반 문서 파이프라인을 강화하기 위해 개발된 강력한 커맨드라인 도구 모음입니다. 콘텐츠를 병합하고, 링크를 검증하고, 네비게이션을 생성하는 등 문서 작성 과정의 다양한 단계를 자동화하여 안정적인 문서 구축을 돕습니다. 개별 도구를 선택해 특정 문서 문제를 해결하거나, CI/CD 워크플로우에 결합하여 반복 가능한 문서 관리 환경을 구축할 수 있습니다.
상세정보
프로그램 소개
DocFx Companion Tools는 DocFX를 사용하는 문서 프로젝트를 위해 특별히 설계된 5개의 독립적인 커맨드라인 도구입니다. 각 도구는 문서 빌드 파이프라인의 특정 단계를 자동화하여 개발자의 생산성을 높이고 문서 품질을 향상시킵니다.
주요 기능
각 도구는 DocFX 문서 워크플로우의 특정 요구사항을 해결합니다.
DocAssembler
여러 저장소나 폴더에 흩어진 문서를 하나로 결합하고 구조화합니다. 경로나 콘텐츠 교체 규칙을 설정하여 링크를 재작성하고 통합된 문서 세트를 생성합니다.
DocFxTocGenerator
폴더 계층 구조를 기반으로 DocFX 네비게이션 파일(toc.yml)을 자동으로 생성합니다. 정렬 순서, 제목, 폴더 참조 등을 설정할 수 있으며, 색인 페이지도 생성합니다.
DocLinkChecker
문서 내의 로컬 및 외부 링크, 앵커, 파이프 테이블, 리소스를 검증하여 배포 전에 문서 문제를 발견합니다. 고아가 된 첨부 파일을 보고하거나 제거하는 기능도 포함되어 있습니다.
DocLanguageTranslator
다국어 문서 구조에서 누락된 현지화 파일을 찾아내고, Azure AI Translator를 사용하여 전체 문서 또는 선택된 라인 범위를 번역합니다.
DocFxOpenApi
OpenAPI v2 또는 v3 형식의 JSON/YAML 파일을 DocFX가 기대하는 OpenAPI v2 JSON 형식으로 변환하여 OpenAPI 콘텐츠를 DocFX를 통해 게시할 수 있게 합니다.
다운로드·설치 방법
도구는 .NET 글로벌 도구 또는 Chocolatey 패키지 관리자를 통해 설치할 수 있습니다. Chocolatey가 설치된 Windows 환경에서는 다음 명령어로 모든 도구를 한 번에 설치할 수 있습니다.
choco install docfx-companion-tools
개별 도구를 .NET 글로벌 도구로 설치하려면 다음 명령어를 사용합니다.
dotnet tool install –global DocLinkChecker
설치된 도구를 나중에 업데이트하려면 다음 명령어를 사용합니다.
dotnet tool update –global DocLinkChecker
기본 사용법
모든 도구는 ‘–help’ 옵션을 통해 상세한 사용법을 확인할 수 있습니다. 예를 들어, 문서 폴더의 링크와 첨부 파일을 검증하고 DocFX 테이블 오브 Contents를 생성하는 명령어는 다음과 같습니다.
DocLinkChecker –docfolder ./docs –attachments –table
DocFxTocGenerator –docfolder ./docs –sequence –override –indexing NotExists
도구들은 0이 아닌 종료 코드를 반환하여 자동화된 빌드의 검증 단계에 적합합니다.
이런 경우에 유용합니다
DocFX를 사용하여 대규모 프로젝트 문서를 관리하는 개발자나 기술 작가에게 유용합니다. 여러 팀이 만든 문서를 하나로 통합하거나, 문서 배포 전에 링크 오류를 자동으로 찾아내야 할 때 효과적입니다. 또한 다국어 문서 번역 자동화나 CI/CD 파이프라인에 문서 검증 단계를 추가해야 하는 경우에도 활용할 수 있습니다.
지원 환경·시스템 요구사항
이 도구들은 Windows, Linux, macOS에서 실행할 수 있으며, .NET 10 런타임이 필요합니다. Docker를 사용하여 컨테이너 환경에서도 실행할 수 있습니다.
시스템 요구사항
도구를 실행하려면 .NET 10 런타임이 설치되어 있어야 합니다. newer major .NET 런타임만 사용 가능한 경우 '--roll-forward Major' 옵션을 사용하여 실행할 수 있습니다.