Docusaurus를 활용한 Doc as a code 및 Github Pages로 Deploy 해보기

이전 포스트에서 우리 팀에서 원하는 기능에 대해서 동작하는지를 테스트 해보는 작업을 했습니다.

Docusaurus를 사용한 Doc as a code Deploy 검토하기

 

위의 테스트를 기반으로 실제 Deploy를 위한 작업을 했습니다.

실제로 필요한 기능들을 사용 해 보면서 Github Pages로 Deploy할 수 있는 Template 코드를 작성했습니다.

Tutorial Intro | Docusaurus Template

 

현재까지 deploy 되어있는 docusaurus 페이지

이를 template으로 사용하여 제가 필요한 기능에 대해서 Github actions로 deploy 하는것을 구성하고 팀에서 바로 사용할 수 있도록 코드를 반영 해 둘 예정입니다.

현재까지 완료된 작업은 아래와 같습니다.

 

깃헙에 반영된 코드

1. docs 폴더에 문서를 관리하고 싶은 repository를 clone 해 두면 그 폴더 구조에 따라서 sidebar를 자동 생성 해 주는 코드 추가. (scripts/createSidebar.cjs)

2. 1.0.0 버전을 새로 생성하고 versioning 반영된 코드

3. Code highlighting for golang and c++

4. Search 기능 지원 (영어만)

 

추가로 반영할 기능

1. 원하는 버저닝 리스트를 추가해서 version 관리하는 코드에 자동 추가하기

2. 특정 페이지를 기반으로 PDF 생성하는 기능 (아마도 Github Actions의 workflow로 지원 가능 할 듯)

github pages로 deploy 한 이후에는 아래의 코드가 동작하여 pdf를 만드는것을 확인했습니다.

다만, 원하는 순서로 pdf를 구성하는것은 아직 정확한 방법은 몰라서 이를 지원해야합니다.

$ npx docs-to-pdf --initialDocURLs="https://ray5273.github.io/docusaurus-template/docs/next/intro" --contentSelector="article" --paginationSelector="a.pagination-nav__link.pagination-nav__link--next" --excludeSelectors=".margin-vert--xl a,[class^='tocCollapsible'],.breadcrumbs,.theme-edit-this-page" --coverImage="https://docusaurus.io/img/docusaurus.png" --coverTitle="Docusaurus v2"

docs-to-pdf.pdf

1.51MB

 

다른 예시를 통해서 PDF를 만들었는데 생각보다 괜찮게 만들어 주기도 합니다.

docs-to-pdf.pdf

0.86MB

3. 위의 다른 header에 다른 문서들을 추가하고 그 문서들 또한 versioning 가능하게 하기

4. OpenAPI documentation 지원 기능 확인 및 Deploy할 수 있게 코드 반영하기

5. 필요한 모든 기능에 대한 문서화