이 기사에서는 단계별 모든 프로젝트에 적용할 수 있는 동적 문서 사이트를 만드는 방법을 안내합니다. 여기서 문서를 데이터베이스에 연결하여 데이터를 추출 및 표시하고 정보를 보장할 수 있습니다. 항상 최신 상태입니다. 또한 AWS를 사용하여 콘텐츠 생성부터 배포까지 클라우드에서 전체 프로세스를 자동화하는 방법도 알아봅니다.
이 솔루션에는 차트 및 다이어그램 지원, GitHub Actions의 간단한 워크플로를 사용한 지속적인 통합(CI/CD), Terraform을 사용한 자동 배포가 포함됩니다. 시작해 보세요!
문서화 및 업데이트는 소프트웨어를 개발하는 많은 회사에서 중요한 프로세스이며, 종종 다양한 도구를 사용하여 수행되며, 그 중 다수는 유료 솔루션입니다.
그래서 최근에는 "doc as code"라는 개념이 등장했습니다. 이는 소프트웨어 개발에 사용되는 것과 동일한 도구 및 워크플로우를 사용하여 문서를 관리, 버전화 및 배포한다는 것을 의미합니다.
이 접근 방식을 사용하면 문서를 더 잘 추적할 수 있을 뿐만 아니라 유지 관리도 용이하고 코드뿐만 아니라 문서에서도 소프트웨어 개발에 사용되는 것과 동일한 모범 사례를 준수할 수 있습니다.
이러한 사이트를 개발하려면 이 접근 방식을 구현할 수 있는 몇 가지 사례와 도구를 이해하는 것이 중요합니다. 다음은 이 튜토리얼에서 다루게 될 가장 중요한 측면에 대한 자세한 목록입니다.
MkDocs는 프로젝트 문서화를 위해 특별히 설계된 ?Python으로 작성된 정적 사이트 생성기입니다. 작성하고 읽기 쉬운 Markdown 파일을 사용하여 문서 작성을 단순화하는 것이 목표입니다.
최소한의 구성으로 MkDocs는 Markdown 파일을 탐색 가능하고 체계적으로 구성된 문서 웹 사이트로 변환하므로 문서를 최신 상태로 유지하려는 개발자와 팀에 이상적입니다.
MkDocs Material은 Google의 Material Design 지침을 따르는 MkDocs의 고급 테마입니다.
Mermaid는 텍스트에서 다이어그램과 차트를 생성하기 위한 JavaScript 라이브러리입니다. MkDocs Material과 통합함으로써 Mermaid를 사용하면 외부 도구 없이도 문서 내에서 순서도, 엔터티 관계 다이어그램 및 기타 차트와 같은 시각화를 생성할 수 있습니다.
Jinja는 Python 사전의 변수와 데이터를 HTML에 삽입하여 웹 페이지를 동적으로 만들 수 있는 라이브러리입니다. 이 라이브러리는 일반적으로 동적 HTML을 생성하고 개인화된 이메일을 보내는 데 사용됩니다.
Docusaurus는 문서 웹 사이트의 생성, 배포 및 유지 관리를 빠르고 효율적으로 단순화하기 위해 2007년 Meta에서 개발한 오픈 소스 프로젝트입니다. Markdown 및 MDX를 사용하여 콘텐츠를 작성할 수 있으며, React를 기반으로 구축된 핵심은 프로젝트의 특정 요구 사항에 맞게 스타일을 완전히 사용자 정의할 수 있습니다.
또한 Docusaurus는 @docusaurus/theme-mermaid 플러그인을 통해 Mermaid를 지원하므로 문서 내에 차트와 다이어그램을 직접 포함할 수 있습니다.
Diagram as Code는 기존 그래픽 도구를 사용하는 대신 코드를 통해 다이어그램을 만들 수 있는 접근 방식입니다. 다이어그램을 수동으로 작성하는 대신 텍스트 파일에 코드를 작성하여 다이어그램의 구조, 구성 요소 및 연결을 정의합니다.
이 코드는 그래픽 이미지로 변환되어 소프트웨어 프로젝트에 더 쉽게 통합하고 문서화할 수 있습니다. 프로그래밍 방식으로 아키텍처 및 흐름도를 생성하고 업데이트하는 데 특히 유용합니다.
앞서 언급했듯이 다이어그램을 사용하면 주요 클라우드 기술의 아이콘을 사용하여 청사진을 생성할 수 있습니다. 이러한 다이어그램의 표현은 노드를 통해 이루어지며, 이 예에서는 클라우드 관련 노드와 AWS 서비스를 모두 사용하겠습니다.
제가 이 코드를 만든 방법에 대한 자세한 내용은 Diagram as Code에 대한 내 기사를 참조하세요. 전체 구현은 다음 저장소에서 찾을 수 있습니다.
r0mymendez
/
코드형 다이어그램
Diagram as Code는 기존 그래픽 도구가 아닌 코드를 통해 다이어그램을 만들 수 있는 접근 방식입니다. 다이어그램을 수동으로 작성하는 대신 텍스트 파일에 코드를 작성하여 다이어그램의 구조, 구성 요소 및 연결을 정의할 수 있습니다.
이 코드는 그래픽 이미지로 변환되어 소프트웨어 프로젝트에 더 쉽게 통합하고 문서화할 수 있으며, 특히 프로그래밍 방식으로 아키텍처 및 흐름도를 생성하고 업데이트하는 데 유용합니다.
다이어그램은 코드형 다이어그램 접근 방식을 구현하는 ?Python 라이브러리로, 코드를 통해 아키텍처 인프라 다이어그램과 기타 유형의 다이어그램을 만들 수 있습니다. 다이어그램을 사용하면 단 몇 줄의 코드만으로 클라우드 인프라 구성 요소(예: AWS, Azure, GCP), 네트워크 요소, 소프트웨어 서비스 등을 쉽게 정의할 수 있습니다.
이 사용 사례에서는 ? 병원 데이터. 목표는 처음에는 MkDocs를 사용하여 대화형 문서 사이트를 구축하고 나중에 Docusaurus로 마이그레이션하는 것입니다. 이 사이트에는 시각적 다이어그램 삽입, SQLite 데이터베이스에서 동적으로 데이터 업데이트 등 특정 요구 사항을 충족하기 위한 정적 및 동적 구성 요소가 모두 포함됩니다.
? 문서 사이트의 주요 기능
를 사용하여 문서 프로젝트를 설정하는 단계를 살펴보고 체계적인 디렉토리 구조를 설명합니다. ? MkDocs의 전제 조건
라이브러리를 설치해야 합니다.
MkDocs 및 자료 설치
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
새로운 MkDocs 프로젝트를 생성하여 시작하세요. 터미널에서 다음 명령을 실행하세요.
mkdocs new mkdocs cd mkdocs
MkDocs 사이트가 생성되면 기본적으로 포함되지 않는 다음 파일과 폴더를 추가해야 합니다.
참고하실 수 있도록 이 게시물 끝에 저장소 링크가 제공되어 있으며, 각 구성 요소는 아래에서 자세히 설명됩니다.
pip install mkdocs mkdocs-material
| 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.yml 파일부터 시작하여 단계별로 구성하겠습니다. 이 파일은 설명서 사이트의 구조와 설정을 정의합니다. 구성 방법은 다음과 같습니다.
mkdocs.yml
pip install mkdocs mkdocs-material
이 구성 파일에서는 주로 nav 섹션에서 메뉴에서 액세스할 수 있는 페이지를 볼 수 있습니다. 그런 다음 다음 섹션에서 설명할 Mermaid 확장을 지정합니다. 마지막으로 테마 섹션에서는 머티리얼 테마를 적용하여 이 라이브러리 내에서 스타일 지정 및 구성 요소를 사용할 수 있습니다.
앞서 언급했듯이 Mermaid는 텍스트를 바탕으로 다이어그램과 차트를 만드는 JavaScript 라이브러리입니다. 아래에서 몇 가지 예를 살펴보겠습니다. 우리의 경우 이를 사용하여 문서의 테이블 페이지에서 엔터티 관계 다이어그램(ERD)을 생성합니다.
저장소에서 공식 Synthea 문서에 있는 ERD(엔티티 관계 다이어그램)를 기반으로 이 코드를 구성하는 방법을 확인할 수 있습니다. 다음 링크에서 테이블 페이지의 예를 확인할 수도 있습니다: tables.md.
문서 사이트의 동적 콘텐츠 생성을 활성화하기 위해 Jinja를 사용하여 템플릿을 처리하고 자리 표시자를 실제 데이터로 대체합니다. 다음은 단계별 분석입니다.
템플릿 폴더 설정
사이트의 모든 Markdown 파일을 저장하기 위해 템플릿이라는 폴더를 만듭니다. 이러한 파일에는 자리 표시자가 포함되어야 합니다. 예를 들어, index.md에는 {{database.version_date}} 및 {{database.version}}과 같은 자리 표시자가 있을 수 있습니다.
자리 표시자 활용
자리 표시자는 Markdown 파일의 동적 변수입니다. 이러한 변수는 관련 데이터를 삽입하기 위해 Python 사전을 사용하여 자동으로 업데이트됩니다.
update.py로 동적 콘텐츠 생성
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
과정은 다음과 같습니다.
? 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
이렇게 하면 문서에 항상 최신 데이터가 반영되어 데이터베이스의 실제 콘텐츠를 기반으로 한 동적 예가 표시됩니다.
다음 섹션에서는 Docusaurus를 사용하여 문서 사이트를 구현하는 방법에 대한 자세한 단계와 통찰력을 제공하겠습니다. 여기에는 설정, 사용자 정의 및 배포 옵션이 포함됩니다.
Docusaurus를 시작하기 위해 우리는 MkDocs에 사용한 단계와 매우 유사하지만 도구가 다른 빠른 설정 프로세스를 따릅니다.
pip install mkdocs mkdocs-material
pip install aiosql pandas sqlite3 jinja2 shutil
mkdocs new mkdocs cd mkdocs
docusaurus.config.js 구성 파일은 제목, 테마, 탐색을 사용자 정의하고 다이어그램 렌더링을 위해 Mermaid와 같은 기능을 활성화하는 곳입니다.
Mermaid 활성화를 위한 예제 스니펫:
pip install mkdocs mkdocs-material
홈페이지를 맞춤설정하기 위해 src/comComponents/HomepageFeatures/index.js 파일을 수정합니다. 여기에서 FeatureList 개체를 조정하여 홈페이지에 표시되는 기능을 업데이트할 수 있습니다.
MkDocs와 마찬가지로 Docusaurus는 콘텐츠에 대한 마크다운 파일을 지원하며 구조를 다음과 같이 구성합니다.
pip install aiosql pandas sqlite3 jinja2 shutil
__category__.json 예:
mkdocs new mkdocs cd mkdocs
데이터베이스 테이블과 같은 동적 콘텐츠를 통합하기 위해 저장소에서 찾을 수 있는 update.py라는 ?Python 스크립트를 사용합니다.
이 스크립트는 SQLite 데이터베이스에서 데이터를 가져와 템플릿 폴더에 저장된 Markdown 파일을 처리합니다. 그런 다음 가져온 데이터로 이러한 파일을 업데이트하고 docs 폴더에 복사하여 사이트 렌더링을 준비합니다.
이 워크플로는 MkDocs로 구현한 것과 유사한 접근 방식에 따라 콘텐츠를 최신 상태로 유지하고 배포할 준비가 되도록 보장합니다.
이 섹션에서는 호스팅용 AWS S3을 사용하여 MkDocs와 Docusaurus의 배포 프로세스를 다룹니다. 두 도구의 배포 단계는 동일하지만 설치 프로세스는 다릅니다. MkDocs는 Python 기반이고 Docusaurus는 JavaScript 기반
입니다.정적 문서 사이트를 AWS S3에 배포하기 위해 Terraform을 사용하여 필요한 리소스를 프로비저닝하고 구성합니다. 설정에서는 S3 버킷을 정의하고, 정적 웹 사이트 호스팅을 활성화하고, 읽기 전용 액세스를 허용하는 버킷 정책으로 퍼블릭 액세스를 구성합니다. 저장소에서 main.tf 파일을 찾을 수 있습니다.
저장소에서 사이트를 배포하기 위한 전체 Terraform 파일과 해당 구성에 액세스할 수 있습니다.
Terraform 구성 파일:
자동 배포를 위한 GitHub 작업 워크플로: 배포 프로세스를 자동화하는 CI/CD 파이프라인도 저장소에 포함되어 있습니다.
GitHub 작업 구성
설정 > 아래의 GitHub 저장소 비밀에서 AWS 자격 증명을 구성해야 합니다. 비밀 > 액션. 이렇게 하면 GitHub Actions가 AWS 계정에 안전하게 액세스하고 변경 사항을 메인 브랜치에 푸시할 때 S3에 파일을 업로드하는 등의 작업을 수행할 수 있습니다.
아래는 문서 사이트를 배포하기 위한 모든 코드에 대한 링크입니다. 유익하셨다면 별⭐️을 남겨주시고 팔로우를 해주시면 새 글 알림을 받아보실 수 있습니다. 이는 제가 기술 커뮤니티에서 성장하고 더 많은 콘텐츠를 만드는 데 도움이 될 것입니다.
r0mymendez
/
문서-코드-mkdocs
MkDocs는 코드로 쉽게 업데이트할 수 있는 문서 포털을 구현하기 위한 탁월한 솔루션으로, 소프트웨어 개발 프로젝트 문서를 최신 상태로 유지하고 버전을 관리하는 데 도움이 됩니다.
이 저장소에서는 데이터 모델과 머신러닝 프로젝트를 문서화하기 위한 간단한 사이트를 만들었습니다.
문서에는 차트, 표, 아키텍처 예제가 포함되어 있어 이 프레임워크를 두 개의 다른 ?Python 라이브러리와 함께 구현하는 방법에 대한 포괄적이고 이해하기 쉬운 가이드를 제공합니다.
문서화 및 업데이트는 소프트웨어를 개발하는 많은 회사에서 중요한 프로세스이며, 이 프로세스는 다양한 도구를 사용하여 수행되며 그 중 다수는 유료 솔루션입니다.
그래서 최근에는 "doc as code"라는 개념이 등장했습니다. 이는 소프트웨어 개발에 사용되는 것과 동일한 도구 및 워크플로우를 사용하여 관리, 버전 관리 및…
r0mymendez
/
문서로서의 코드-docusaurus
Docusaurus는 코드로 쉽게 업데이트할 수 있는 문서 포털을 구현하기 위한 탁월한 솔루션으로, 소프트웨어 개발 프로젝트 문서를 최신 상태로 유지하고 버전을 관리하는 데 도움이 됩니다.
이 저장소에서는 데이터 모델과 머신러닝 프로젝트를 문서화하기 위한 간단한 사이트를 만들었습니다.
문서에는 차트, 표, 아키텍처 예제가 포함되어 있어 이 프레임워크를 두 개의 다른 ?Python 라이브러리와 함께 구현하는 방법에 대한 포괄적이고 이해하기 쉬운 가이드를 제공합니다.
문서화 및 업데이트는 소프트웨어를 개발하는 많은 회사에서 중요한 프로세스이며, 이 프로세스는 다양한 도구를 사용하여 수행되며 그 중 다수는 유료 솔루션입니다.
그래서 최근에는 "doc as code"라는 개념이 등장했습니다. 이는 소프트웨어 개발에 사용되는 것과 동일한 도구 및 워크플로우를 사용하여 문서를 관리, 버전화 및 배포하는 것을 의미합니다…
두 솔루션 모두 구현하기 쉽지만 다음 항목에서 몇 가지 차이점을 살펴볼 수 있으며 구현해야 할 상황, 지식, 복잡성에 따라 가장 좋은 솔루션이 달라집니다.
위 내용은 AWS에 Docs-as-Code 배포: MkDocs 및 Docusaurus에서 동적 문서 사이트 구축의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!
![[웹 프런트엔드] Node.js 빠른 시작](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
