AWS에 Docs-as-Code 배포: MkDocs 및 Docusaurus에서 동적 문서 사이트 구축
- Mary-Kate Olsen원래의
- 2024-11-28 05:28:11201검색
이 기사에서는 단계별 모든 프로젝트에 적용할 수 있는 동적 문서 사이트를 만드는 방법을 안내합니다. 여기서 문서를 데이터베이스에 연결하여 데이터를 추출 및 표시하고 정보를 보장할 수 있습니다. 항상 최신 상태입니다. 또한 AWS를 사용하여 콘텐츠 생성부터 배포까지 클라우드에서 전체 프로세스를 자동화하는 방법도 알아봅니다.
이 솔루션에는 차트 및 다이어그램 지원, GitHub Actions의 간단한 워크플로를 사용한 지속적인 통합(CI/CD), Terraform을 사용한 자동 배포가 포함됩니다. 시작해 보세요!
코드로서의 문서화란 무엇입니까?
문서화 및 업데이트는 소프트웨어를 개발하는 많은 회사에서 중요한 프로세스이며, 종종 다양한 도구를 사용하여 수행되며, 그 중 다수는 유료 솔루션입니다.
그래서 최근에는 "doc as code"라는 개념이 등장했습니다. 이는 소프트웨어 개발에 사용되는 것과 동일한 도구 및 워크플로우를 사용하여 문서를 관리, 버전화 및 배포한다는 것을 의미합니다.
이 접근 방식을 사용하면 문서를 더 잘 추적할 수 있을 뿐만 아니라 유지 관리도 용이하고 코드뿐만 아니라 문서에서도 소프트웨어 개발에 사용되는 것과 동일한 모범 사례를 준수할 수 있습니다.
코드로 문서화하기 위한 도구
이러한 사이트를 개발하려면 이 접근 방식을 구현할 수 있는 몇 가지 사례와 도구를 이해하는 것이 중요합니다. 다음은 이 튜토리얼에서 다루게 될 가장 중요한 측면에 대한 자세한 목록입니다.
- ? 마크다운: 단순성과 버전 제어 플랫폼 및 정적 사이트 생성기와의 통합으로 인해 문서 작성에 가장 일반적인 마크업 언어입니다.
- ?️ Git: Git을 사용하면 코드와 마찬가지로 문서 버전 관리가 가능합니다. Git 덕분에 문서의 모든 변경 사항이 기록되므로 팀에서는 편집 내용을 추적하고 변경 사항을 되돌리고 보다 효율적으로 협업할 수 있습니다.
- ? Gitflow: 이 방법론은 문서의 버전과 개정판을 관리하는 구조화된 워크플로를 제공하여 변경 사항이 프로덕션에 도달하기 전에 승인 및 테스트되도록 합니다. Gitflow는 또한 팀 간의 협업을 촉진하여 안전하고 체계적인 변경 관리를 가능하게 합니다.
- ☁️ 클라우드 서비스: AWS S3, Netlify 또는 GitHub 페이지와 같은 서비스를 사용하면 저렴한 비용으로 문서를 배포할 수 있습니다. 이러한 서비스를 사용하면 빠르고 안전하며 쉽게 액세스할 수 있는 정적 사이트를 만들 수 있습니다.
- ? 정적 사이트 생성기: Docusaurus, Jekyll 또는 Hugo와 같은 도구는 Markdown 문서를 탐색 가능한 웹사이트로 변환하여 서버 없이 풍부하고 체계적인 문서를 만들 수 있도록 해줍니다.
- ? 지속적 통합(CI/CD): CI/CD 파이프라인(예: GitHub Actions, GitLab CI 또는 Jenkins)을 사용하면 새 버전이 병합되거나 수정 사항이 승인될 때 문서를 자동으로 배포할 수 있습니다. 이렇게 하면 문서가 항상 최신 상태로 유지됩니다.
Docs-as-Code의 장점
- ✅ 일관성 및 품질: 버전 제어 및 변경 검토를 사용하여 문서의 일관성과 높은 품질을 유지합니다.
- ⚙️ 자동화: CI/CD 도구를 사용하면 문서 배포를 자동화하여 업데이트 시간을 줄이고 오류를 최소화할 수 있습니다.
- ? 효율적인 협업: Git과 같은 도구를 사용하면 팀이 충돌 없이 문서를 작성하고 유지 관리하기 위해 협업할 수 있습니다.
- ? 단순화된 유지 관리: 문서 유지 관리가 개발 워크플로에 통합되어 코드가 발전함에 따라 업데이트가 더 쉬워집니다.
? MkDocs
MkDocs는 프로젝트 문서화를 위해 특별히 설계된 ?Python으로 작성된 정적 사이트 생성기입니다. 작성하고 읽기 쉬운 Markdown 파일을 사용하여 문서 작성을 단순화하는 것이 목표입니다.
최소한의 구성으로 MkDocs는 Markdown 파일을 탐색 가능하고 체계적으로 구성된 문서 웹 사이트로 변환하므로 문서를 최신 상태로 유지하려는 개발자와 팀에 이상적입니다.
✏️ MkDocs 자료
MkDocs Material은 Google의 Material Design 지침을 따르는 MkDocs의 고급 테마입니다.
? 주요 기능은 다음과 같습니다:
- ? 반응형 디자인: 모든 화면 크기에 자동으로 적응합니다.
- ? 사용자 정의: 프로젝트의 시각적 정체성에 맞게 색상, 글꼴, 파비콘, 로고를 쉽게 수정할 수 있습니다.
- ? 검색 인터페이스: 고급 검색은 결과를 그룹화하고 검색어를 강조 표시하여 사용자가 필요한 정보를 찾는 데 도움을 줍니다.
- ⚡ 지연 로딩: 검색 결과에 지연 로딩을 구현하여 성능을 개선하고 로드 시간을 줄입니다.
- ? 통합: Google Analytics, Disqus 및 GitHub와 호환되어 트래픽 분석, 사용자 피드백 및 프로젝트 저장소에 대한 직접 연결이 용이합니다.
✏️ 인어
Mermaid는 텍스트에서 다이어그램과 차트를 생성하기 위한 JavaScript 라이브러리입니다. MkDocs Material과 통합함으로써 Mermaid를 사용하면 외부 도구 없이도 문서 내에서 순서도, 엔터티 관계 다이어그램 및 기타 차트와 같은 시각화를 생성할 수 있습니다.
? 동적 페이지: Jinja
Jinja는 Python 사전의 변수와 데이터를 HTML에 삽입하여 웹 페이지를 동적으로 만들 수 있는 라이브러리입니다. 이 라이브러리는 일반적으로 동적 HTML을 생성하고 개인화된 이메일을 보내는 데 사용됩니다.
? 도쿠사우루스 개요
Docusaurus는 문서 웹 사이트의 생성, 배포 및 유지 관리를 빠르고 효율적으로 단순화하기 위해 2007년 Meta에서 개발한 오픈 소스 프로젝트입니다. Markdown 및 MDX를 사용하여 콘텐츠를 작성할 수 있으며, React를 기반으로 구축된 핵심은 프로젝트의 특정 요구 사항에 맞게 스타일을 완전히 사용자 정의할 수 있습니다.
또한 Docusaurus는 @docusaurus/theme-mermaid 플러그인을 통해 Mermaid를 지원하므로 문서 내에 차트와 다이어그램을 직접 포함할 수 있습니다.
? 코드로서의 다이어그램
Diagram as Code는 기존 그래픽 도구를 사용하는 대신 코드를 통해 다이어그램을 만들 수 있는 접근 방식입니다. 다이어그램을 수동으로 작성하는 대신 텍스트 파일에 코드를 작성하여 다이어그램의 구조, 구성 요소 및 연결을 정의합니다.
이 코드는 그래픽 이미지로 변환되어 소프트웨어 프로젝트에 더 쉽게 통합하고 문서화할 수 있습니다. 프로그래밍 방식으로 아키텍처 및 흐름도를 생성하고 업데이트하는 데 특히 유용합니다.
? 코드형 다이어그램: 클라우드 다이어그램 생성 예
앞서 언급했듯이 다이어그램을 사용하면 주요 클라우드 기술의 아이콘을 사용하여 청사진을 생성할 수 있습니다. 이러한 다이어그램의 표현은 노드를 통해 이루어지며, 이 예에서는 클라우드 관련 노드와 AWS 서비스를 모두 사용하겠습니다.
제가 이 코드를 만든 방법에 대한 자세한 내용은 Diagram as Code에 대한 내 기사를 참조하세요. 전체 구현은 다음 저장소에서 찾을 수 있습니다.
r0mymendez
/
코드형 다이어그램
'Doc as Diagram' 방법론을 사용하여 문서 프로젝트를 생성하는 방법에 대한 튜토리얼
? 코드형 다이어그램: 시각적 콘텐츠를 위한 동적 및 대화형 문서 생성
Diagram as Code는 기존 그래픽 도구가 아닌 코드를 통해 다이어그램을 만들 수 있는 접근 방식입니다. 다이어그램을 수동으로 작성하는 대신 텍스트 파일에 코드를 작성하여 다이어그램의 구조, 구성 요소 및 연결을 정의할 수 있습니다.
이 코드는 그래픽 이미지로 변환되어 소프트웨어 프로젝트에 더 쉽게 통합하고 문서화할 수 있으며, 특히 프로그래밍 방식으로 아키텍처 및 흐름도를 생성하고 업데이트하는 데 유용합니다.
다이어그램이란 무엇인가요?
다이어그램은 코드형 다이어그램 접근 방식을 구현하는 ?Python 라이브러리로, 코드를 통해 아키텍처 인프라 다이어그램과 기타 유형의 다이어그램을 만들 수 있습니다. 다이어그램을 사용하면 단 몇 줄의 코드만으로 클라우드 인프라 구성 요소(예: AWS, Azure, GCP), 네트워크 요소, 소프트웨어 서비스 등을 쉽게 정의할 수 있습니다.
? 코드형 다이어그램의 장점
- ?…
? 사용 사례: 기계 학습 프로젝트를 위한 문서 사이트 만들기
이 사용 사례에서는 ? 병원 데이터. 목표는 처음에는 MkDocs를 사용하여 대화형 문서 사이트를 구축하고 나중에 Docusaurus로 마이그레이션하는 것입니다. 이 사이트에는 시각적 다이어그램 삽입, SQLite 데이터베이스에서 동적으로 데이터 업데이트 등 특정 요구 사항을 충족하기 위한 정적 및 동적 구성 요소가 모두 포함됩니다.
? 문서 사이트의 주요 기능- 시각적 표현
- : 머신러닝 파이프라인의 아키텍처를 효과적으로 설명하기 위해 다이어그램(Diagram as Code)으로 만든 다이어그램을 삽입합니다. 동적 데이터 업데이트
- : 문서에는 버전과 마지막 업데이트 날짜가 동적으로 표시되며 정확성과 관련성을 보장하기 위해 SQLite 데이터베이스에서 이 정보를 가져옵니다. 데이터 샘플
- : 문서에는 합성 데이터를 예로 보여주는 Synthea 환자 테이블의 샘플이 포함됩니다.
이러한 이유로 당사 문서 사이트에는 다음 페이지가 있습니다.
- ? 홈
- : 문서 홈페이지 ? 테이블
- :신시아 데이터 테이블과 그 용도에 대한 설명 ? 아키텍처
- :AWS에서 호스팅되는 데이터 처리 아키텍처에 대한 자세한 개요 ? 용어집
- : 프로젝트 전반에 걸쳐 사용되는 용어집
이 섹션에서는 처음부터
MkDocs를 사용하여 문서 프로젝트를 설정하는 단계를 살펴보고 체계적인 디렉토리 구조를 설명합니다. ? MkDocs의 전제 조건
시작하려면 다음
?Python라이브러리를 설치해야 합니다.
MkDocs 및 자료 설치
pip install mkdocs mkdocs-material동적 콘텐츠 업데이트를 활성화하려면 추가 라이브러리 설치
pip install aiosql pandas sqlite3 jinja2 shutil? Mkdocs: 프로젝트 설정
프로젝트 초기화
새로운 MkDocs 프로젝트를 생성하여 시작하세요. 터미널에서 다음 명령을 실행하세요.
mkdocs new mkdocs cd mkdocs디렉토리 구조 탐색
MkDocs 사이트가 생성되면 기본적으로 포함되지 않는 다음 파일과 폴더를 추가해야 합니다.
참고하실 수 있도록 이 게시물 끝에 저장소 링크가 제공되어 있으며, 각 구성 요소는 아래에서 자세히 설명됩니다.
pip install mkdocs mkdocs-material
?Mkdocs: 구성 요소 개요
| Component | Directory | Description |
|---|---|---|
| Database (db) | db | Contains the SQLite database (hospital.db) and queries (metadata.sql, person.sql) to manage dynamic data. Learn more about managing SQL queries in Python in my previous article: Python Projects with SQL. |
| ?️ Templates & Pages | template | Markdown templates: index.md, tables.md, architecture.md, glossary.md. Supports Mermaid diagrams, embedded images, and database-driven content. |
| ?️ Static Content (docs) | docs | Final site generated by update.py, including images (img/) and dynamic content populated from template. |
| ? Infrastructure (infraestructure) | infraestructure | Terraform scripts (main.tf, variables.tf) to deploy an S3 bucket for documentation hosting. |
? Mkdocs: mkdocs.yml 구성
프로젝트 구조가 설정되면 mkdocs.yml 파일부터 시작하여 단계별로 구성하겠습니다. 이 파일은 설명서 사이트의 구조와 설정을 정의합니다. 구성 방법은 다음과 같습니다.
mkdocs.yml
pip install mkdocs mkdocs-material
이 구성 파일에서는 주로 nav 섹션에서 메뉴에서 액세스할 수 있는 페이지를 볼 수 있습니다. 그런 다음 다음 섹션에서 설명할 Mermaid 확장을 지정합니다. 마지막으로 테마 섹션에서는 머티리얼 테마를 적용하여 이 라이브러리 내에서 스타일 지정 및 구성 요소를 사용할 수 있습니다.
✏️ Mkdocs: 인어 확장
앞서 언급했듯이 Mermaid는 텍스트를 바탕으로 다이어그램과 차트를 만드는 JavaScript 라이브러리입니다. 아래에서 몇 가지 예를 살펴보겠습니다. 우리의 경우 이를 사용하여 문서의 테이블 페이지에서 엔터티 관계 다이어그램(ERD)을 생성합니다.
저장소에서 공식 Synthea 문서에 있는 ERD(엔티티 관계 다이어그램)를 기반으로 이 코드를 구성하는 방법을 확인할 수 있습니다. 다음 링크에서 테이블 페이지의 예를 확인할 수도 있습니다: tables.md.
⚙️ Mkdocs: Jinja를 사용한 동적 콘텐츠
문서 사이트의 동적 콘텐츠 생성을 활성화하기 위해 Jinja를 사용하여 템플릿을 처리하고 자리 표시자를 실제 데이터로 대체합니다. 다음은 단계별 분석입니다.
템플릿 폴더 설정
사이트의 모든 Markdown 파일을 저장하기 위해 템플릿이라는 폴더를 만듭니다. 이러한 파일에는 자리 표시자가 포함되어야 합니다. 예를 들어, index.md에는 {{database.version_date}} 및 {{database.version}}과 같은 자리 표시자가 있을 수 있습니다.자리 표시자 활용
자리 표시자는 Markdown 파일의 동적 변수입니다. 이러한 변수는 관련 데이터를 삽입하기 위해 Python 사전을 사용하여 자동으로 업데이트됩니다.-
update.py로 동적 콘텐츠 생성
- 동적 데이터가 필요한 섹션을 식별하여 마크다운 템플릿을 준비하세요.
- 내 저장소에 있는 Python 스크립트(update.py)를 사용하여 템플릿을 처리합니다. 스크립트는 다음 작업을 수행합니다.
- 데이터베이스 연결: SQLite 데이터베이스에 연결하여 최신 값을 가져옵니다.
- 템플릿 렌더링: Jinja 라이브러리를 사용하여 자리 표시자를 데이터베이스의 데이터로 대체합니다.
- 파일 생성: 업데이트된 Markdown 파일을 docs 폴더에 출력하여 MkDocs에서 렌더링할 준비가 됩니다.
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
이러한 단계를 따르면 설명서 사이트의 업데이트 프로세스를 자동화하여 수동으로 편집하지 않고도 콘텐츠가 동적이고 관련성을 유지하도록 할 수 있습니다.
데이터 테이블의 동적 업데이트
다음 예에서는 데이터베이스의 persons 테이블 예를 보여주기 위해 tables.md 파일의 내용을 업데이트합니다. 이를 위해 Markdown 파일 내에 자리 표시자 {{table.person}}을 만듭니다. 아이디어는 persons 테이블에서 데이터를 동적으로 가져온 다음 Jinja 라이브러리를 pandas와 함께 사용하여 쿼리 결과를 Markdown 테이블 형식으로 변환하는 것입니다.
다음은 자리표시자와 함께 tables.md 파일이 어떻게 보이는지에 대한 예입니다.
mkdocs new mkdocs cd mkdocs
과정은 다음과 같습니다.
- 데이터베이스 쿼리: 스크립트는 SQLite 데이터베이스의 persons 테이블을 쿼리하여 관련 레코드를 가져옵니다.
- 마크다운으로 변환: pandas를 사용하면 쿼리 결과가 마크다운 테이블 형식으로 변환됩니다.
- 자리 표시자 바꾸기: tables.md 파일의 {{table.person}} 자리 표시자는 생성된 Markdown 테이블로 대체됩니다.
? docs/
├── ? img/
├── `architecture.md`
├── `glossary.md`
├── `index.md`
├── `tables.md`
├── ? template/
│ ├── ? db/
│ │ ├── ? data/
│ │ │ ├── hospital.db
│ │ ├── ? queries/
│ ├── `architecture.md`
│ ├── `glossary.md`
│ ├── `index.md`
│ ├── `tables.md`
│ └── `update.py`
? infraestructure/
? github/
├── ? workflows/
│ ├── main.yml
? mkdocs.yml
이렇게 하면 문서에 항상 최신 데이터가 반영되어 데이터베이스의 실제 콘텐츠를 기반으로 한 동적 예가 표시됩니다.
⚙️ Mkdocs: 최종 작업 흐름
- 템플릿 만들기: docs/template 디렉토리에서 페이지를 개발하세요.
- update.py 실행: 동적 콘텐츠를 채우고 문서/출력에 최종 파일을 생성합니다.
- 로컬에서 미리보기: mkdocs 서브를 사용하여 localhost에서 사이트를 미리 봅니다.
- 배포용 빌드: mkdocs build를 사용하여 docs/ 폴더에 정적 사이트를 생성합니다.
- 배포: Terraform을 사용하여 AWS S3 버킷에 사이트를 배포합니다. 자세한 지침은 이 게시물의 배포 섹션을 참조하세요.
? 도쿠사우루스 구현
다음 섹션에서는 Docusaurus를 사용하여 문서 사이트를 구현하는 방법에 대한 자세한 단계와 통찰력을 제공하겠습니다. 여기에는 설정, 사용자 정의 및 배포 옵션이 포함됩니다.
? 도쿠사우루스의 주요 특징
- ? Mermaid 지원: MkDocs와 유사하게 Docusaurus는 다이어그램 삽입을 위해 Mermaid를 지원합니다.
- ⚛️ React 구성 요소: React를 기반으로 구축된 Docusaurus를 사용하면 동적 구성 요소를 문서에 통합할 수 있습니다.
- ? 동적 콘텐츠: Python 스크립트를 활용하여 SQLite 데이터베이스에서 콘텐츠를 동적으로 가져오고 업데이트합니다.
? Docusaurus 설정: 처음부터
Docusaurus를 시작하기 위해 우리는 MkDocs에 사용한 단계와 매우 유사하지만 도구가 다른 빠른 설정 프로세스를 따릅니다.
- 새 Docusaurus 프로젝트 만들기: 먼저 Node.js를 설치하고 다음 명령을 실행하여 새 Docusaurus 사이트를 만듭니다.
pip install mkdocs mkdocs-material
- 인어 패키지 설치: Mermaid 다이어그램을 활성화하려면 필수 패키지를 설치하십시오.
pip install aiosql pandas sqlite3 jinja2 shutil
- 개발 서버 실행: 설치가 완료되면 프로젝트 디렉터리로 이동하여 개발 서버를 실행합니다.
mkdocs new mkdocs cd mkdocs
- 사이트 방문: 귀하의 사이트는 http://localhost:3000에서 로컬로 운영됩니다.
? Docusaurus 사용자 정의: 구성
docusaurus.config.js 구성 파일은 제목, 테마, 탐색을 사용자 정의하고 다이어그램 렌더링을 위해 Mermaid와 같은 기능을 활성화하는 곳입니다.
Mermaid 활성화를 위한 예제 스니펫:
pip install mkdocs mkdocs-material
? Docusaurus 홈페이지 사용자 정의
홈페이지를 맞춤설정하기 위해 src/comComponents/HomepageFeatures/index.js 파일을 수정합니다. 여기에서 FeatureList 개체를 조정하여 홈페이지에 표시되는 기능을 업데이트할 수 있습니다.
? Docusaurus 콘텐츠 구성 및 구조
MkDocs와 마찬가지로 Docusaurus는 콘텐츠에 대한 마크다운 파일을 지원하며 구조를 다음과 같이 구성합니다.
- 템플릿 폴더: Markdown 파일을 docs/template 디렉터리에 저장하고 Python 스크립트(update.py와 유사)를 만들어 동적 데이터를 가져와 이러한 템플릿에 채웁니다.
- 카테고리 파일(__category__.json): 사이드바의 문서 순서를 관리하려면 각 폴더에 __category__.json 파일을 만듭니다. 예를 들어:
pip install aiosql pandas sqlite3 jinja2 shutil
__category__.json 예:
mkdocs new mkdocs cd mkdocs
⚙️ Jinja의 동적 데이터
데이터베이스 테이블과 같은 동적 콘텐츠를 통합하기 위해 저장소에서 찾을 수 있는 update.py라는 ?Python 스크립트를 사용합니다.
이 스크립트는 SQLite 데이터베이스에서 데이터를 가져와 템플릿 폴더에 저장된 Markdown 파일을 처리합니다. 그런 다음 가져온 데이터로 이러한 파일을 업데이트하고 docs 폴더에 복사하여 사이트 렌더링을 준비합니다.
이 워크플로는 MkDocs로 구현한 것과 유사한 접근 방식에 따라 콘텐츠를 최신 상태로 유지하고 배포할 준비가 되도록 보장합니다.
⚙️ Docusaurus: 최종 작업 흐름
- 템플릿 만들기: docs/template 디렉토리 내에서 Markdown 파일을 개발하세요.
- Python 스크립트 실행: 스크립트를 사용하여 템플릿에 데이터를 동적으로 채웁니다.
- 로컬에서 미리보기: npx docusaurus start를 실행하여 사이트를 미리보세요.
- 배포용 빌드: 준비되면 npx docusaurus 빌드를 사용하여 정적 사이트를 생성합니다.
- 배포: AWS S3 등 원하는 플랫폼에 정적 파일을 호스팅합니다.
? 전개
이 섹션에서는 호스팅용 AWS S3을 사용하여 MkDocs와 Docusaurus의 배포 프로세스를 다룹니다. 두 도구의 배포 단계는 동일하지만 설치 프로세스는 다릅니다. MkDocs는 Python 기반이고 Docusaurus는 JavaScript 기반
입니다.Terraform을 사용한 인프라 설정
정적 문서 사이트를 AWS S3에 배포하기 위해 Terraform을 사용하여 필요한 리소스를 프로비저닝하고 구성합니다. 설정에서는 S3 버킷을 정의하고, 정적 웹 사이트 호스팅을 활성화하고, 읽기 전용 액세스를 허용하는 버킷 정책으로 퍼블릭 액세스를 구성합니다. 저장소에서 main.tf 파일을 찾을 수 있습니다.
? S3 배포를 위한 주요 구성 요소
- S3 버킷 생성: 문서가 호스팅될 S3 버킷을 생성하는 리소스입니다.
- 정적 웹사이트 호스팅: 정적 웹 호스팅을 위한 구성, index.html 및 error.html을 기본 문서 및 오류 문서로 설정합니다.
- 공개 액세스 구성: S3 버킷에 대한 공개 액세스를 관리하여 읽기 전용 액세스로 구성되도록 합니다.
- 버킷 정책: S3 버킷에서 문서 콘텐츠를 검색하기 위한 공개 액세스를 허용합니다.
저장소에서 사이트를 배포하기 위한 전체 Terraform 파일과 해당 구성에 액세스할 수 있습니다.
Terraform 구성 파일:
- mkdocs 파일
- 도쿠사우루스 파일
자동 배포를 위한 GitHub 작업 워크플로: 배포 프로세스를 자동화하는 CI/CD 파이프라인도 저장소에 포함되어 있습니다.
- mkdocs 파일
- 도쿠사우루스 파일
GitHub 작업 구성
설정 > 아래의 GitHub 저장소 비밀에서 AWS 자격 증명을 구성해야 합니다. 비밀 > 액션. 이렇게 하면 GitHub Actions가 AWS 계정에 안전하게 액세스하고 변경 사항을 메인 브랜치에 푸시할 때 S3에 파일을 업로드하는 등의 작업을 수행할 수 있습니다.
저장소
아래는 문서 사이트를 배포하기 위한 모든 코드에 대한 링크입니다. 유익하셨다면 별⭐️을 남겨주시고 팔로우를 해주시면 새 글 알림을 받아보실 수 있습니다. 이는 제가 기술 커뮤니티에서 성장하고 더 많은 콘텐츠를 만드는 데 도움이 될 것입니다.
- MkDocs 배포: MkDocs용 GitHub 저장소
r0mymendez
/
문서-코드-mkdocs
'Doc as Code' 방법론을 사용하여 문서 프로젝트를 생성하는 방법에 대한 튜토리얼
⚙️ Doc as Code 튜토리얼
? MkDocs 및 MkDocs 자료
MkDocs는 코드로 쉽게 업데이트할 수 있는 문서 포털을 구현하기 위한 탁월한 솔루션으로, 소프트웨어 개발 프로젝트 문서를 최신 상태로 유지하고 버전을 관리하는 데 도움이 됩니다.
이 저장소에서는 데이터 모델과 머신러닝 프로젝트를 문서화하기 위한 간단한 사이트를 만들었습니다.
문서에는 차트, 표, 아키텍처 예제가 포함되어 있어 이 프레임워크를 두 개의 다른 ?Python 라이브러리와 함께 구현하는 방법에 대한 포괄적이고 이해하기 쉬운 가이드를 제공합니다.
코드로서의 문서화란 무엇입니까?
문서화 및 업데이트는 소프트웨어를 개발하는 많은 회사에서 중요한 프로세스이며, 이 프로세스는 다양한 도구를 사용하여 수행되며 그 중 다수는 유료 솔루션입니다.
그래서 최근에는 "doc as code"라는 개념이 등장했습니다. 이는 소프트웨어 개발에 사용되는 것과 동일한 도구 및 워크플로우를 사용하여 관리, 버전 관리 및…
- Docusaurus 배포: Docusaurus용 GitHub 저장소
r0mymendez
/
문서로서의 코드-docusaurus
'Doc as code' 방법론을 사용하여 문서 프로젝트를 생성하는 방법에 대한 튜토리얼
⚙️ Doc as Code 튜토리얼
? 도쿠사우루스
Docusaurus는 코드로 쉽게 업데이트할 수 있는 문서 포털을 구현하기 위한 탁월한 솔루션으로, 소프트웨어 개발 프로젝트 문서를 최신 상태로 유지하고 버전을 관리하는 데 도움이 됩니다.
이 저장소에서는 데이터 모델과 머신러닝 프로젝트를 문서화하기 위한 간단한 사이트를 만들었습니다.
문서에는 차트, 표, 아키텍처 예제가 포함되어 있어 이 프레임워크를 두 개의 다른 ?Python 라이브러리와 함께 구현하는 방법에 대한 포괄적이고 이해하기 쉬운 가이드를 제공합니다.
코드로서의 문서화란 무엇입니까?
문서화 및 업데이트는 소프트웨어를 개발하는 많은 회사에서 중요한 프로세스이며, 이 프로세스는 다양한 도구를 사용하여 수행되며 그 중 다수는 유료 솔루션입니다.
그래서 최근에는 "doc as code"라는 개념이 등장했습니다. 이는 소프트웨어 개발에 사용되는 것과 동일한 도구 및 워크플로우를 사용하여 문서를 관리, 버전화 및 배포하는 것을 의미합니다…
? 최종 결론: MkDocs 대 Docusaurus
두 솔루션 모두 구현하기 쉽지만 다음 항목에서 몇 가지 차이점을 살펴볼 수 있으며 구현해야 할 상황, 지식, 복잡성에 따라 가장 좋은 솔루션이 달라집니다.
- ? 언어 및 사용자 정의: MkDocs는 Python 기반이며 간단한 YAML 구성과 템플릿을 갖추고 있어 빠른 설정에 이상적입니다. 반면 Docusaurus는 React 기반으로 고급 사용자 정의 및 대화형 구성 요소를 제공하므로 시각적 요소에 대한 더 많은 제어가 필요한 사용자에게 더 적합합니다.
- ? 마크다운 및 렌더링: 둘 다 Markdown을 사용하지만 Docusaurus에서는 대화형 요소를 허용하므로 동적 콘텐츠에 더 좋습니다.
- ⚙️ 복잡성: Docusaurus는 로그인 시스템과 같은 복잡한 문서 애플리케이션에 더 적합합니다. MkDocs는 더 간단하지만 Docusaurus는 스타일과 기능에 있어 더 많은 유연성을 제공합니다.
- ? 커뮤니티: Docusaurus는 Discord와 74개의 플러그인을 갖춘 강력한 커뮤니티를 보유하고 있는 반면, MkDocs는 커뮤니티 지원을 위해 GitHub 토론에 의존합니다.
- ☁️ Amazon 배포: S3에 정적 사이트를 배포하여 배포 비용을 절감할 수 있으며, CI/CD를 사용하여 자동 배포할 수도 있습니다.
? 참고자료
- Mkdocs: https://www.mkdocs.org/
- Mkdocs-재료: https://squidfunk.github.io/mkdocs-material/
- 다이어그램: https://diagrams.mingrammer.com/
- 도쿠사우루스: https://docusaurus.io/
- 진자: https://jinja.palletsprojects.com/en/stable/
- Git Book - doc as code란 무엇입니까: https://www.gitbook.com/blog/what-is-docs-as-code
- 문서 작성: https://www.writethedocs.org/guide/docs-as-code/
위 내용은 AWS에 Docs-as-Code 배포: MkDocs 및 Docusaurus에서 동적 문서 사이트 구축의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!