코드로서의 문서 작업: Python 라이브러리 문서화.

문서는 대상 고객이 제품을 효과적으로 사용하는 방법을 이해하는 데 도움이 되는 중요한 리소스입니다. 고품질 문서는 제품이 해결하는 핵심 문제를 전달할 뿐만 아니라 사용자가 원하는 결과를 원활하게 달성할 수 있도록 지원합니다.

오픈소스 라이브러리와 패키지도 마찬가지입니다. 개발자에게 이러한 도구를 프로젝트에 성공적으로 통합하는 방법을 안내하려면 명확하고 접근 가능한 문서가 필수적입니다.

최근 몇 년 동안 문서화에 대한 Docs-as-Code(DaC) 접근 방식이 큰 인기를 얻었습니다. 이 방법은 개발자가 코드에 사용하는 것과 동일한 도구 및 프로세스를 사용하여 문서를 소프트웨어 개발 수명주기의 기본 부분으로 처리합니다.

이 방법은 제품과 함께 발전하는 일관되고 버전 관리되며 쉽게 유지 관리할 수 있는 문서를 촉진하기 때문에 널리 받아들여지고 있습니다.

코드형 문서(Docs-as-Code)란 무엇입니까?

간단히 말하면 DaC는 코드와 마찬가지로 문서를 처리하고 유지 관리하는 방법입니다.

일반적인 소프트웨어 개발 수명 주기에는 다음을 포함하는 7단계가 포함됩니다.

1. 기획
2. 요구사항 수집 및 분석
3. 디자인
4. 코딩 및 구현
5. 코드 테스트
6. 코드 배포
7. 코드 유지관리

따라서 DaC는 문서가 동일한 단계를 거치도록 보장하는 새로운 접근 방식입니다. 이렇게 하면 문서의 버전이 관리되고 소프트웨어 변경 사항에 따라 최신 상태로 유지됩니다.

DaC 없이 배포

DaC를 사용한 배포

이 가이드에서는 DaC의 이론적인 측면을 심층적으로 다루지 않을 수 있지만 DaC의 개념을 자세히 설명하는 초보자용 Docs-as-code 기사를 살펴볼 수 있습니다.

프로젝트 개요

이 가이드에는 Python을 사용한 DaC의 실제 구현이 포함되어 있습니다. Mintlify를 사용하여 오픈 소스 Python 라이브러리를 문서화하는 방법을 배웁니다.

Mintlify는 공개 문서에 사용되는 정적 사이트 생성기이자 문서 사이트입니다. 개발자 문서, API 문서 등 다양한 문서 요구 사항에 맞게 유지 관리하고 사용하기 쉽습니다. 또한 DaC 방법론과도 잘 작동합니다.

이 튜토리얼은 Python 라이브러리를 구축하고 배포하는 방법에 대한 기존 튜토리얼의 후속편입니다. DaC 방법론을 사용하여 Python 라이브러리 개발 참조 튜토리얼을 문서화하는 방법을 배우게 됩니다.

계속하기 전에 이전 튜토리얼을 완료하는 것이 좋습니다. 하지만 이 튜토리얼에 사용할 기존 프로젝트가 있으면 계속 진행할 수 있습니다.

프로젝트 요구사항

Git 및 GitHub에 대한 기본 지식, Github 저장소를 생성하는 방법, GitHub에 코드를 푸시하는 방법이 필요합니다. 이 튜토리얼에는 다음 도구도 필요합니다.

• Mintlify 계정: 문서를 작성하려면 활성화된 Mintlify 계정이 필요합니다(단계는 가이드에 제공됩니다).
• Node.js: Mintlify를 설치하고 로컬에서 문서를 편집하려면 Node.js 버전 18 이상이 필요합니다.

Mintlify 문서 설정

Mintlify를 사용하여 문서를 설정하려면 아래 단계를 따르세요.

1. Mintlify에서 계정을 만드세요

2. Mintlify 계정 설정:
확인 링크가 귀하의 메일로 전송됩니다. 이 링크를 클릭하면 아래 페이지로 리디렉션됩니다:

3. Github로 로그인하세요:
첫 번째 단계에서는 Github 계정으로 로그인해야 합니다.

4. 문서용 GitHub 저장소(repo)를 만드세요.
다음 단계에서는 Github 계정에 Mintlify 앱을 설치하고 승인해야 합니다. 이를 통해 Mintlify가 자동으로 문서 저장소를 생성할 수 있습니다

5. 문서 저장소에 액세스하세요:
이전 단계에서는 문서에 대한 새 문서 저장소를 만듭니다. 새로운 문서 저장소에 대한 GitHub 저장소를 확인하세요

프로젝트에 문서 추가

다음 단계는 문서 저장소를 로컬 환경에 복제하고 이를 개발자 도구, 오픈 소스 패키지 등과 같은 기존 프로젝트에 추가하는 것입니다. 이전 튜토리얼을 이미 완료한 경우 프로젝트는 exchangeLibrary가 됩니다.

프로젝트에 문서를 추가하려면 아래 단계를 따르세요.

1. 터미널을 열고 아래 명령을 사용하여 문서 저장소를 복제하세요.

git clone https://github.com/<your github username>/docs 
</your>

2. 복제된 docs 폴더를 프로젝트에 복사하세요.

3. 코드 편집기에서 프로젝트를 엽니다.

이제 프로젝트 파일 구조는 다음과 같습니다.

로컬에서 문서 미리보기

Mintlify를 사용하면 문서를 게시하기 전에 로컬에서 미리 볼 수 있습니다. 설정하려면 아래 단계를 따르세요.
1. 터미널에서 프로젝트를 엽니다
2. Mintlify를 전역적으로 설치하려면 아래 명령을 실행하세요.

git clone https://github.com/<your github username>/docs 
</your>

3. 프로젝트의 docs 폴더로 전환하세요:

npm i -g mintlify

4. 아래 명령을 사용하여 mintlify 서버를 시작하십시오.

cd docs

터미널에 아래와 같은 메시지가 표시됩니다.

문서를 로컬에서 미리 보려면 URL을 엽니다. 문서의 내용은 Mintlify 시작 문서 템플릿이 됩니다. 문서 편집을 시작하면 변경됩니다.

문서 작성

Mintlify 문서는 mint.json 파일을 기반으로 합니다. 이 파일에는 문서의 색 구성표, 페이지 매기기 및 탐색 설정이 포함되어 있습니다. 프로젝트의 docs 폴더에서 찾을 수 있습니다.

또한 Mintlify의 문서 파일은 .mdx로 작성됩니다. 특수 태그 및 기호를 허용한다는 점을 제외하면 markdown(.md)과 거의 유사합니다.

이 섹션에서는 mint.json 파일에서 문서 설정을 편집하는 방법과 문서에 텍스트 및 특수 구성요소를 추가하는 방법을 알아봅니다.

문서 설정 편집

mint.json 파일은 문서의 색 구성표, 페이지 매김, 탐색 설정 등으로 구성된 JSON 개체입니다. 다음은 사용 가능한 설정 목록과 그 의미입니다.

1. 색상 구성 및 외관:
이 섹션은 문서의 모양을 아름답게 하고 향상시키는 데 사용됩니다. 문서의 로고(밝은 모드와 어두운 모드 모두), 파비콘, 제목 및 색 구성표를 변경하는 데 사용됩니다. 아래와 같이 $schema 키부터 색상 키까지 시작합니다.

mintlify dev

2. 탐색 링크 및 CTA 버튼:
이 섹션은 문서 페이지 상단의 탐색 링크와 버튼을 설정하는 데 사용됩니다. 다음은 탐색 링크와 버튼의 예입니다.

아래 코드는 Mintlify 문서에 대한 탐색 링크와 CTA 버튼을 설정합니다.

  "$schema": "https://mintlify.com/schema.json",
  "name": "<your-documentation-title>",
  "logo": {
    "dark": "<logo-for-dark-mode>",
    "light": "<logo-for-light-mode>"
  },
  "favicon": "<link-to-a-favicon>",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },
</link-to-a-favicon></logo-for-light-mode></logo-for-dark-mode></your-documentation-title>

3. 탭 및 앵커:
탭과 앵커를 사용하여 문서에서 각각 가로 및 세로 섹션을 설정할 수 있습니다. 다음은 탭의 예입니다.

다음은 앵커의 예입니다.

이러한 구성요소의 설정은 탭 및 앵커 키로 처리됩니다.

4. 탐색 설정:
이 섹션은 문서의 페이지를 그룹화하는 데 도움이 됩니다. 그룹 키로 구성된 배열과 그룹에 대한 페이지가 순차적으로 추가되는 페이지 배열입니다. 다음은 추가 방법의 예입니다.

git clone https://github.com/<your github username>/docs 
</your>

위 설정은 아래 이미지로 변환됩니다.

페이지(소개 등)는 프로젝트의 docs 폴더에 있는 .mdx 파일입니다.

5. 중첩된 탐색:
중첩된 탐색은 일반적으로 문서 내에 하위 섹션을 만드는 데 사용됩니다. 다음은 중첩된 탐색의 예입니다.

다음은 Mintlify에서 중첩 탐색을 설정하는 샘플 코드입니다.

npm i -g mintlify

위 코드는 섹션/그룹을 다른 섹션 내에 중첩합니다. 아이콘 키는 웹페이지에 렌더링될 때 아이콘으로 섹션 제목을 아름답게 만듭니다.

6. 바닥글 설정:
footerSocials 키는 문서와 관련된 소셜 미디어 계정을 추가하는 데 사용됩니다. 아래는 예시입니다:

콘텐츠를 추가하는 방법

Mintlify 문서는 문서에 콘텐츠를 추가하는 방법을 안내합니다. 문서에 다양한 콘텐츠를 추가하는 방법을 알아보려면 문서를 확인해 보시기 바랍니다.

문서 구성 방법에 대한 영감을 얻으려면 이 샘플 문서를 확인하세요.

문서 작성 팁

다음은 명확하고 사용자 친화적인 문서를 작성하는 데 도움이 되는 몇 가지 팁입니다.

1. 최대한 직접적으로 작성하세요. 가치를 더하지 않는 불필요한 정보는 피하세요. 귀하의 문서는 다음 프로젝트에서 귀하의 패키지나 도구를 사용하려는 개발자를 위한 것이므로 이를 달성하는 데 필요한 것만 보여주십시오.

2. 도구에 대한 설명이나 개요를 추가하세요.
도구 사용 방법을 자세히 설명하기 전에 도구가 무엇인지, 도구가 해결하는 문제에 대해 간략하게 설명하세요. 이 내용은 첫 페이지에 있어야 합니다.

3. 충분한 코드 샘플을 추가하세요.
이는 불필요한 오류 없이 도구를 사용하는 방법을 이해하는 데 도움이 됩니다. 설치, 인증, 응답 샘플, 메서드 인수 등에 대한 코드 샘플은 매우 중요합니다.

4. 오류 및 예외:
이는 사용자가 디버깅하는 데 도움이 됩니다. 도구를 사용할 때 사용자가 겪을 수 있는 오류 종류를 설명하는 페이지를 추가하세요. 이에 대한 코드 샘플도 보여주세요.

프로젝트를 Github에 푸시

프로젝트를 Github에 푸시하려면 아래 단계를 따르세요.

1. 프로젝트에서 git bash 터미널을 열고 아래 명령을 사용하여 docs 폴더로 전환하세요.

git clone https://github.com/<your github username>/docs 
</your>

2. 아래 명령을 사용하여 이 폴더에서 git을 제거합니다.

npm i -g mintlify

이 명령은 전체 프로젝트를 Github에 푸시할 때 문제를 방지하기 위해 docs 폴더에서 .git을 제거합니다.

3. 프로젝트를 GitHub에 푸시하세요.

문서 배포

Mintlify에 문서를 배포하려면 아래 단계를 따르세요.
1. Mintlify 대시보드에 로그인하세요
2. 설정 탭을 클릭하세요

3. Mintlify Github 저장소를 프로젝트 저장소로 변경하세요

4. 모노레포 스위치를 활성화합니다. 이는 docs 폴더가 단일 저장소의 다른 프로젝트 내에 존재한다는 것을 의미합니다.

5. 나타나는 새 필드에 mint.json 파일의 경로로 **docs를 입력합니다.**

6. 변경 사항을 저장하려면 저장 버튼을 클릭하세요.

대시보드의 개요 탭에 표시된 링크를 통해 문서에 액세스할 수 있습니다

프로젝트 업데이트

프로젝트를 변경하고 재배포해야 할 가능성이 가장 높습니다.

프로젝트를 업데이트한 후 변경 사항을 Github에 푸시하세요. Mintlify는 자동으로 새로운 변경 사항을 선택하고 즉시 문서를 업데이트합니다.

결론

이 튜토리얼에서는 코드형 문서 접근 방식을 사용하여 Python 라이브러리용 문서를 작성하는 방법을 배웠습니다.

Docs-as-Code는 프로젝트에 대한 협업과 지속적인 통합을 촉진합니다. 오픈 소스의 경우 docs-as-code를 사용하면 사람들이 적절한 최신 문서를 유지하면서 프로젝트에서 원활하게 협업할 수 있습니다.

SDK나 프로그래밍 라이브러리가 없는 다양한 REST API가 있습니다. 관심 있는 것을 선택하고 비슷한 것을 만들어 보세요.

계속 구축하세요 ?‍?!

자주 묻는 질문

문서를 어떻게 테스트할 수 있나요?

이 기능은 여러 기여자가 참여하는 대규모 프로젝트에서 자주 사용됩니다. 문서 테스트는 프로젝트에 끌어오기 요청이 있을 때 자동으로 실행됩니다. 테스트가 성공하면 변경 사항이 병합됩니다. 더 자세히 알아보려면 swimm이 자동 문서 테스트를 제공하는 방법에 대한 이 가이드를 읽어보세요.

이 프로젝트를 다른 프로그래밍 언어로 복제할 수 있나요?
예, 가능합니다. 선호하는 언어로 비슷한 결과를 얻으려면 이 가이드의 절차를 따르세요.

Mintlify 외에 다른 문서 사이트가 있나요?
예, 사용할 수 있는 다른 문서 사이트가 있습니다. 그 중 일부는 다음과 같습니다: Gitbook, Readme, Docusaurus 등

위 내용은 코드로서의 문서 작업: Python 라이브러리 문서화.의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!