Skip to content

Latest commit

 

History

History
106 lines (84 loc) · 4.61 KB

tools_and_setup.adoc

File metadata and controls

106 lines (84 loc) · 4.61 KB

빌드 환경 세팅하기, 빌드하기

AsciiBinder 설치하기

HyperCloud documentation은 AsciiDoc으로 이루어져 있고, AsciiDoctor 기반의 문서 관리 시스템인 AsciiBinder으로 빌드한다.

CentOS 7.7.1908에서 아래와 같이 ascii_binder와 그 dependencies를 차례로 설치한다. (다른 Linux System에서도 할 수 있겠지만, 아래의 가이드는 CentOS 7.7.1908 에서의 재현이 보장된다.)

  1. yum install rubygems

  2. yum install ruby-devel

  3. yum install gcc-c++

  4. yum install redhat-rpm-config

  5. yum install make

  6. gem install asciidoctor-diagram --version=1.5.6

  7. gem install ascii_binder --version=0.1.15.3

위의 단계 7.에서 에러가 발생하면, 아래를 추가로 진행한다.

  1. gem install "rubygems-update:<3.0.0" --no-document

  2. update_rubygems

  3. gem install ffi -v 1.12.2

  4. gem install rb-inotify -v 0.9.10

  5. gem install listen -v 3.0.8

  6. gem install lumberjack -v 1.0.13

  7. gem install ascii_binder --version=0.1.15.3

AsciiBinder 코드 수정하기

순정 상태의 AsciiBinder는 한국어를 제대로 지원하지 못한다. 그 이유는 아래와 같다.

Note

docs를 빌드하면, 상단 breadcrumb 및 좌측 LNB tree의 각 node에 ID가 자동으로 부여된다.
이러한 ID는 각 노드에 부여된 이름에서 (1차) 영문/숫자/공백만 남기고,
다음으로 (2차) 공백들을 제거하면서 camel case 형식으로 이어붙이는 방식으로 생성된다.

이때 ID가 빈 스트링인 경우가 있거나 중복되는 경우가 있으면 빌드가 되지 않거나, 빌드 후 정상 동작이 보장되지 않는다.

한국어로 된 목차구성을 지원하기 위해, 다음과 같이 AsciiBinder에서 topic id를 생성하는 방식을 변경해주자. /usr/local/share/gems/gems/ascii_binder-0.1.15.3/lib/ascii_binder/topic_entity.rb 파일을 열어서, 184라인을 다음과 같이 수정한다.

...
    def id
      ### @id ||= hierarchy.map{ |entity| camelize(entity.name) }.join('::') ########### -> 기존 코드 제거, 혹은 주석 처리
      @id ||= hierarchy.map{ |entity| entity.name.unpack('U*').join('.') }.join('::') ### -> 새로운 코드 삽입
    end
...

빌드하기

테스트 목적으로 빌드하는 경우

  1. hypercloud-docs 프로젝트 폴더를 위 AsciiBinder가 설치된 환경(이하 '빌드환경')에 (FTP 등으로) 업로드한다. (.git 파일도 포함되어 있어야 한다.)

  2. cd hypercloud-docs

  3. chmod +x create_symlink.sh

  4. ./create_symlink.sh

    Note

    • create_symlink.sh 를 실행하면 파일명이 'images’이거나 'modules’인 것을 symbolic link로 변환해준다.
      image나 module을 참조하는 adoc 파일의 부모 폴더에는 images와 modules 이름을 가지는 파일이 있어야 한다.

    • create_symlink.sh 를 실행하면서 /bin/bash^M: bad interpreter 에러가 발생하면,
      vi create_symlink.sh , Esc 키, :set fileformat=unix , :wq 를 차례로 입력하여 해결할 수 있다.

  5. asciibinder build

  6. 빌드 결과로써 생성된 hypercloud-docs/_preview 폴더를 다운로드하고, 웹 서버에 띄워 테스트한다.

  7. 빌드환경에서 hypercloud-docs 프로젝트 폴더를 삭제한다.

배포용 소스를 생성할 목적으로 빌드하는 경우

  • AsciiBinder가 설치된 환경에서 git clone, 모든 브랜치 pull을 하고, 각 브랜치를 체크아웃하며 빌드한다.

    ### 한 줄씩 말고 통째로 복사-붙여넣기 하시면 됩니다.

rm -rf hypercloud-docs

git clone https://github.com/tmax-cloud/hypercloud-docs.git

cd hypercloud-docs

git branch -r | grep -v '\->' | while read remote; do git branch --track "${remote#origin/}" "$remote"; done
git fetch --all
git pull --all
git branch -r | grep -v '\->' | while read remote; do git checkout "${remote#origin/}"; asciibinder build; done
    Note

    위 코드뭉치를 사용하려면, linux의 symbolic link가 모든 브랜치에 정상적으로 생성되어 있어야 한다.
    symbolic link 문제로 이미지 참조가 안 되면, linux 환경에서 각 브랜치에 symbolic link를 생성하여 commit하고 push하여야 한다.
    (master 브랜치에서 이를 먼저 진행한 후 다른 브랜치에서 cherry pick 또는 merge)