[#manual_management] = 매뉴얼 관리 Heywon Choi <heywon.choi@bankwareglobal.com> [abstract] .문서개요 -- 이 문서는 AsciiDoc 으로 작성하는 {doctitle} 에 대해 설명합니다. 매뉴얼 관련된 리소스들은 GitLab을 통해서 유지 관리되고 관리 주체는 다음과 같다. * SWD팀: 관련 리소스와 매뉴얼탬플릿 그리고 시각화를 위한 Style, CSS 등을 유지 관리한다. * R&D팀: 각 제품별, 버전별로 매뉴얼을 작성하고 유지 관리한다. -- == Repository 구조 ---- 📒 repository (swlab-docs) <1> 📄 antora-playbook.yml <2> 📂 getting-started <3> 📄 antora.yml <4> 📂 modules <5> 📂 ROOT <6> 📂 images <8> 📄 image-source-file.png <9> 📂 pages <10> 📄 page-source-file.adoc <11> 📄 nav.adoc <12> 📂 guide-like-bgbook <7> 📂 images 📄 image-source-file.png 📂 pages 📄 page-source-file.adoc 📄 nav.adoc 📂 ready-to-write <7> 📂 images 📄 image-source-file.png 📂 pages 📄 page-source-fi le.adoc 📄 nav.adoc ---- <1> 팀별로 구성 <2> 필수 구성 파일 : 사이트, 콘텐츠 원본 및 UI URL을 구성 <3> 콘텐츠 원본 루트 <4> 필수 구성 파일 : 이름, 버전, 메타데이터, 속성 및 탐색 목록을 구성 <5> 필수 모듈 디렉토리 <6> ROOT 모듈 디렉토리 : ROOT 모듈의 페이지는 컴포넌트 버전의 최상위 페이지가 되므로 다른 모듈에서 참조하는 공통 리소스를 저장한다. + [CAUTION] ==== 기본 셋팅되어 있는 리소스는 수정/제거하지 않도록 주의한다. ==== <7> 명명된 모듈 디렉토리 : 필요한 만큼 생성 가능하고 생성할 때는 xref:00aboutManual.adoc#module_name_rule["모듈 디렉토리 명명 규칙"]에 준하여 생성한다. <8> 이미지 디렉터리 : 이미지 파일이 없다면 생성하지 않는다. 필요 시 지정된 이름 'images'로 생성한다. <9> 이미지 소스 파일 : PNG, JPG, SVG 및 GIF(정적 및 애니메이션) 이미지 파일 형식을 지원한다. <10> pages 디렉토리 : 하나 이상의 AsciiDoc 소스 파일이 포함되어야 한다. <11> 페이지의 원본 파일 : AsciiDoc 구문으로 마크업되고 유효한 .adoc 파일 확장명으로 저장된 페이지 파일 <12> 내비게이션 파일 : 사이트 탐색 파일로써 모듈당 하나의 탐색 파일을 가진다. xref:00aboutManual.adoc#nav_file["내비게이션 파일"]을 참고하여 작성한다. === 필수 구성 파일 ==== antora-playbook.yml antora-playbook.yml 파일은 Antora 프로젝트에서 사이트를 생성하기 위해 사용되는 주요 설정 파일로써 사이트의 전반적인 설정을 정의한다. [source,yaml] ---- site: <1> title: SWLab Docs Site url: https://swlab.bwg.co.kr/docs content: <2> sources: - url: https://gitlab.bwg.co.kr/swd/swlab-docs.git branches: [master, v1.0] start_path: getting-started asciidoc: <3> attributes: experimental: '' ui: <4> bundle: url: https://gitlab.bwg.co.kr/swd/swlab-ui/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable snapshot: true output: <5> destinations: - provider: fs path: /data/home/bxdocs/web/docs ---- .antora-playbook.yml 키 설명 [cols="25,75a"] |=== |키 |설명 |1) site |* **수정금지!** 사이트 제목, URL을 설정한다. |2) content |* Antora가 빌드할 문서의 소스를 정의한다. 각 소스는 Git 리포지토리 URL, 브랜치, 시작 경로 등을 포함한다. |3) asciidoc |* **수정금지!** 사이트 전체에 적용되는 AsciiDoc 문서에서 사용할 전역 속성을 설정한다. |4) ui |* **수정금지!** 사이트에서 사용할 UI 번들을 정의한다. |5) output |* **수정금지!** 빌드된 사이트의 파일이 저장될 디렉토리를 정의한다. |=== [#antora_yml] ==== antora.yml antora.yml 파일은 Antora 프로젝트에서 각 컴포넌트의 메타데이터와 설정을 정의하는 파일이다. 각 컴포넌트의 루트 디렉토리에 위치하며, 컴포넌트의 버전을 식별, 설명 및 구성하는 필수 및 선택적 정보를 제공한다. [source,yaml] ---- name: swlab-docs <1> title: SWLab Docs <2> version: '2.0' <3> start_page: ready-to-write:text-editor.adoc <4> asciidoc: <5> attributes: source-language: asciidoc@ nav: <6> - modules/ready-to-write/nav.adoc - modules/guide-like-bgbook/nav.adoc ---- .antora.yml 키 설명 [cols="25,75a"] |=== |키 |설명 |1) name |* **수정금지!** 컴포넌트 버전을 식별하는 데 사용되는 컴포넌트 이름으로 리소스 ID의 컴포넌트 좌표 및 컴포넌트 버전의 게시된 리소스에 대한 컴포넌트 URL 세그먼트에서 사용된다. |2) title |* **수정금지!** 왼쪽 메뉴 페이지에 표시되는 목적으로 사용되는 컴포넌트 이름으로 공백, 대문자 및 다양한 문자를 사용할 수 있다. |3) version |* 컴포넌트 버전을 식별하는 데 사용되는 버전으로 리소스 ID의 버전 좌표 및 컴포넌트 버전의 게시된 리소스 URL에 대한 버전 세그먼트로 사용된다. |4) start_page |* **수정금지!** 페이지를 컴포넌트 버전의 홈 페이지로 지정한다. 형식) 모듈명:페이지 (ROOT모듈은 모듈명 작성시 생략한다.) |5) asciidoc.attributes |* **수정금지!** 컴포넌트 버전에 속하는 모든 페이지와 리소스(해당되는 경우)에 적용할 AsciiDoc 속성 및 페이지 속성을 설정한다. |6) nav |* 왼쪽 메뉴 페이지 구성에 사용될 탐색 파일 목록을 설정한다. ** 한 줄에 하나씩 입력한다. ** 들여쓰지 않는다. ** 각 값을 하이픈(-)으로 시작하고 그 뒤에 공백을 입력한다. ** 공백 뒤에 antora.yml 파일의 위치를 기준으로 개별 탐색 파일의 경로를 입력한다. ** 나열된 순서로 왼쪽 메뉴 페이지가 구성된다. |=== [#module_name_rule] === 모듈 디렉토리 명명 규칙 모듈 이름은 페이지, 이미지, 첨부 파일, 예제 및 부분의 리소스 ID에서 모듈 좌표로 사용된다. 또한 해당 모듈에 할당된 게시 가능한 리소스의 URL에도 사용된다(ROOT 모듈 제외). 따라서 모듈 폴더 이름을 선택할 때 다음 사항을 지켜 생성한다. * 공백이나 슬래시(/)를 포함할 수 없다. * 대문자, 밑줄(_) 및 URL에서 권장되지 않는 기타 문자를 사용하지 않는다. * 너무 길거나 기억하기 어렵게 만들지 말고 짧고 설명적으로 만든다. [#nav_file] === 내비게이션 파일 탐색 파일은 사이트의 왼쪽메뉴를 구성한다. 작성 방법은 다음과 같다. ==== 파일 이름 및 형식 탐색 파일은 **nav.adoc**으로 명명한다. 탐색 파일에는 하나 이상의 글머리 기호 목록이 포함되어 있다. 목록의 각 항목은 페이지에 대한 상호 참조, 사이트에 속하지 않은 웹 사이트의 URL 또는 중첩된 목록 항목 집합을 그룹화하는 범주 제목과 같은 연결되지 않은 텍스트일 수 있다. ==== 목록 구조 탐색 목록은 순서가 지정되지 않은 AsciiDoc 목록이다. 파일에 여러 목록이 포함된 경우 각 목록은 목록 제목으로 시작해야 하고 각 최상위 목록 항목은 최대 2 Level까지만 허용한다. [NOTE] ==== 최상위 목록 항목은 점(.)으로 표시되는 목록 제목이거나, 목록 제목이 없는 경우 단일 별표(*)로 표시된 각 목록 항목을 말한다. ==== [discrete] ==== AsciiDoc 소스 탐색 파일을 작성하는 AsciiDoc 소스는 다음과 같다. [source,asciidoc] ---- .가이드 * xref:00aboutManual.adoc[] ** xref:00_1writing.adoc[] * xref:01title.adoc[] ---- [discrete] ==== 결과 탐색 파일을 작성한 메뉴 형태는 다음과 같다. [NOTE] ==== 메뉴의 각 항목은 문서 제목으로 표시된다. 문서 제목과 다른 항목명으로 표시하고 싶다면 [] 안에 작성한다. ==== **** .Navigation file (Site) image::figure0_1.png["내비게이션 파일",800] **** ==== 내비게이션 등록 필수 구성 파일인 xref:00_2management.adoc#antora_yml["antora.yml"]에 등록한다. == 버전 관리 Antora는 Git 리포지토리의 브랜치를 통해 각기 다른 문서 버전을 관리한다. 각 브랜치는 독립된 문서 버전을 나타내며, 이를 통해 여러 버전의 문서를 동시에 관리하고 배포할 수 있다. === Repository 구성 각 브랜치는 각각의 문서 버전을 나타낸다. master 브랜치는 최신 버전을, v1.0 브랜치는 1.0 버전을 나타낼 수 있다. === Antora Playbook 파일 설정 antora-playbook.yml 파일에서 각 브랜치를 소스로 추가한다. [source,yaml] ---- content: sources: - url: https://gitlab.bwg.co.kr/swd/swlab-docs.git branches: [master, v1.0] <1> start_path: getting-started ---- <1> master 브랜치는 최신 버전을, v1.0 브랜치는 1.0 버전을 나타낼 수 있다. === 컴포넌트 설정 (antora.yml) 각 브랜치의 루트 디렉토리에 위치한 antora.yml 파일을 통해 해당 버전의 메타데이터를 정의한다. master 브랜치는 최신 버전을, 1.0 브랜치는 1.0 버전을 나타낸다. [NOTE] ==== 브랜치명은 version 의 'v'를 prefix로 생성한다. ==== ==== master 브랜치의 antora.yml 파일 [discrete] ==== 버전이 하나만 존재할 경우 [source,yaml] ---- version: '1.0' <1> ---- <1> branch 명: v1.0 [discrete] ==== 버전이 추가되었을 경우 [source,yaml] ---- version: '2.0' <1> ---- <1> 최신 버전을 기입한다. == 다국어 관리 국제화를 위해서 각 나라의 언어별로 프로젝트를 구분하여 리소스를 관리하는 구조를 갖고 있다.