개념(Concepts)
이 페이지는 Backstage에서 Spotify의 docs-like-code 솔루션과 함께 도입된 개념들을 설명해요.
출처: 문서
본문
이 페이지는 Backstage에서 Spotify의 docs-like-code 솔루션과 함께 도입된 개념들을 설명해요.
TechDocs 생성 단계
TechDocs Preparer
Preparing(준비)은 엔티티에 대한 문서를 생성하는 첫 단계예요. 소스 코드 호스팅 제공자(GitHub, GitLab 등)에서 소스 markdown 파일을 가져와 다음 단계를 위해 그 파일들을 generator에 넘겨요.
두 종류의 preparer가 있어요.
-
Common Git Preparer - 어떤 저장소 URL이든
git clone을 사용함. -
URL Reader - 소스 코드 호스팅 제공자의 API를 사용해 파일을 다운로드함. (더 빠르고 권장됨)
TechDocs Generator
Generating(생성)은 markdown 소스 파일을 준비한 다음의 두 번째 단계예요. 이 단계는 TechDocs 컨테이너(아래 정의)를 실행하거나 mkdocs CLI를 실행해 정적 HTML 파일과 그 에셋을 생성해요.
TechDocs Publisher
Publishing(게시)은 문서를 준비하고 생성한 다음의 세 번째이자 마지막 단계예요. TechDocs Publisher가 생성된 파일을 저장소에 업로드해요.
techdocs-backend 플러그인에는 현재 Google Cloud Storage와 Local Filesystem 두 가지 publisher가 함께 제공돼요. Backstage 앱에서 이것들을 구성할 수 있어요. 여기를 참고하세요.
TechDocs publisher는 두 가지 역할을 담당해요(techdocs-backend와 저장소 사이의 양방향 통신).
-
생성된 정적 파일을 저장소에 게시하기(
techdocs.builder로 구성됨) -
사용자가 TechDocs 사이트를 방문할 때 저장소에서 파일 읽기
TechDocs 백엔드
TechDocs 빌드 전략(Build Strategy)
TechDocs를 빌드할지 여부를 둘러싼 더 복잡한 로직을 수용하기 위해, TechDocs 백엔드는 빌드 전략(Build Strategy)을 선택하는 것을 지원해요. 빌드 전략은 요청된 문서를 TechDocs 백엔드가 로컬로 빌드해야 하는지 여부를 결정하는 책임을져요. 빌드 전략을 커스터마이즈하면, TechDocs 백엔드가 빌드를 담당하는지, 외부 프로세스가 담당하는지, 아니면 로컬 빌드와 외부 프로세스의 조합이 담당하는지를 엔티티별로 결정하는 더 복잡한 동작이 가능해져요.
기본 빌드 전략은 techdocs.builder 구성 옵션이 'local'로 설정된 경우 TechDocs 백엔드가 문서를 로컬로 빌드하고, 그 외에는 빌드를 건너뛰는 결과를 내요. 그러나 빌드 전략 인터페이스를 충족하는 어떤 로직이든 구현할 수 있어요. Backstage 구성을 사용하는 동시에 처리 중인 엔티티를 사용해 결정을 내리면 되죠.
빌드 전략을 사용해 '하이브리드' 빌드 모델을 구현하는 방법의 예는 하이브리드 빌드 전략 구현 가이드를 참고하세요.
TechDocs 컨테이너
TechDocs 컨테이너는 DockerHub에서 제공되는 Docker 컨테이너예요. MkDocs를 통해 Python 스타일의 Markdown에서 스타일시트와 스크립트를 포함한 정적 HTML 페이지를 빌드해요.
TechDocs 컨테이너
TechDocs 코어 플러그인(Core Plugin)
TechDocs Core Plugin은 여러 MkDocs 플러그인과 Python Markdown 확장을 감싸는 래퍼로 만들어진 MkDocs 플러그인이에요. TechDocs에 사용되는 MkDocs 구성을 표준화하기 위한 목적이에요.
TechDocs Core
TechDocs CLI
TechDocs CLI는 문서를 작성·생성·미리보기해 게시하기 쉽게 만들어진 도구예요. 현재는 대부분 TechDocs 컨테이너를 감싸는 래퍼 역할을 하고, 우리 docker 컨테이너를 위한 사용하기 쉬운 인터페이스를 제공해요.
TechDocs CLI
TechDocs Reader
TechDocs가 생성한 문서는 정적 HTML 사이트로 생성돼요. 그래서 TechDocs Reader는 미리 생성된 HTML 사이트를 Backstage UI와 통합하기 위해 만들어졌어요.
TechDocs Reader
Transformers
Transformers는 TechDocs Reader 안에서 사용되는 여러 기능 조각이에요. Transformers를 도입한 이유는 렌더 전후에 HTML 콘텐츠를 변환하는 방법(예: 문서 링크 다시 쓰기, css 수정)을 제공하기 위해서예요.
Transformers API 문서
TechDocs Addons
Addons(Backstage v1.2에서 도입)는 읽기 시점(read-time)에 TechDocs 경험을 보강하는 데 쓸 수 있는 클라이언트 측의 React 기반 확장이에요. TechDocs Reader를 조직의 필요에 더 잘 맞게 구성하는 메커니즘을 제공해요.
Addon은 TechDocs Reader 어디에서든, 정적으로 생성된 콘텐츠 안에서도 정보를 동적으로 로드하고 표시할 수 있어요.
Addon을 mkdocs 플러그인과 혼동하면 안 돼요. mkdocs 플러그인은 빌드 시점(build-time)에 TechDocs 사이트의 콘텐츠를 커스터마이즈하는 데 쓸 수 있기 때문이에요. 일부 mkdocs 플러그인의 이점을 취할 수는 있지만, 모든 플러그인이 TechDocs와 잘 동작하는 것은 아니에요(주로, 전적으로는 아니지만, 보안 때문). Addon이 대안을 제공해요.