성능 공동 파일럿 프로젝트

이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

오픈소스 조직:
성능 공동 파일럿
테크니컬 라이터:
arzoo14
프로젝트 이름:
다이어그램 개선이라는 확장 목표에 따라 도서 프로젝트 영역 콘텐츠를 readthedocs 및 reStructuredText 형식으로 변환합니다.
프로젝트 기간:
표준 기간 (3개월)

Project description

추상:

커뮤니티 웹사이트는 커뮤니티에서 제공하는 제품, 귀중한 기여, 기술, 문서, 튜토리얼 등을 전파하기 때문에 오픈소스 조직에서 필수적인 역할을 합니다. 따라서 본 프로젝트는 도서 프로젝트 영역 콘텐츠(예: Docbook 콘텐츠, REST API 문서 및 pbench 사이트의 최신 문서, REST API 문서 및 pbench 사이트의 최신 문서를 읽을 수 있는)를 전송 및 업데이트하여 모든 오픈소스 기여자의 사용성과 용이성을 높이는 것을 목표로 합니다. 또한 이 프로젝트는 커뮤니티 참여자가 콘텐츠를 더 쉽게 변경하고 확장할 수 있도록 함으로써 도움이 될 것입니다. 뿐만 아니라, 도움말의 다이어그램을 개선하여 보다 전문적인 느낌을 줄 수 있습니다.

제안:

  1. 개요: 현재 Performance Co-Pilot 문서는 여러 가지 형식으로 제공됩니다. 여기에는 문서북 형식의 PCP 도서, 맨페이지 형식의 REST API, 마크다운 형식의 pbench 가이드가 포함됩니다. 따라서 조직의 현재 유지관리자 그룹은 유지보수가 거의 필요하지 않으며 개발자 커뮤니티가 간소화되고 쉬운 방법으로 콘텐츠를 유지관리하는 데 전적으로 집중할 수 있는 솔루션이 필요하다는 사실을 깨달았습니다. 따라서 조직의 현재 요구에 따라 이번 Google Docs 시리즈를 통해 다음과 같은 목표를 구현할 것입니다.

    1. 문서북 콘텐츠를 reStructuredText 형식으로 변환하고 readthedocs 사이트에 호스팅
    2. REST API 문서를 맨페이지에서 개발자 친화적인 형식(예: reStructuredText 형식)으로 변환하고 readthedocs 사이트에서 호스팅
    3. pbench MarkDown 콘텐츠를 reStructuredText 형식으로 변환하고 readthedocs 사이트에서 호스팅
    4. 확장 목표는 문서에 있는 다이어그램을 개선하는 것입니다.

  2. 구현: 현재 Performance Co-Pilot 문서는 특정 형식으로 제공되지 않습니다. 문서의 내용을 변경해야 할 때마다 제한된 사용자가 변경해야 합니다. 활동적인 커뮤니티 회원이 문서의 내용을 변경하고 확장하기는 쉽지 않습니다.

reStructuredText 형식, 문서 읽기 (RTD), Sphinx의 도움을 받아 GSoD 기간에 조직이 이러한 한계를 극복할 수 있도록 하겠습니다.

Docs 읽기 (RTD)는 문서 빌드, 버전 관리, 호스팅을 자동화하여 소프트웨어 문서를 단순화합니다. Sphinx에서 생성된 문서를 위한 호스팅 플랫폼입니다. Sphinx의 강력한 기능을 활용하여 버전 제어, 전체 텍스트 검색, 기타 유용한 기능을 추가합니다. Git, Mercurial 또는 Subversion에서 코드와 문서 파일을 가져온 다음 문서를 빌드하고 호스팅합니다. 이 프로젝트에서는 코드 액세스에 가장 일반적으로 사용되는 시스템인 GitHub를 사용하겠습니다.

먼저 Docs 읽기 계정을 만들고 GitHub 계정을 연결합니다. 그런 다음 문서를 빌드할 GitHub 저장소를 선택합니다. 그러면 마법이 시작됩니다.

문서를 읽고 다음과 같이 합니다. - 저장소를 클론합니다. - 마스터 브랜치에서 HTML, PDF, ePub 버전의 문서를 만듭니다. - 전체 텍스트 검색이 가능하도록 문서의 색인을 생성합니다. - 저장소의 각 태그와 브랜치에서 버전 객체를 만들어 선택적으로 호스팅할 수 있습니다. - 저장소에서 웹훅을 활성화하여 브랜치에 코드를 푸시하면 문서가 다시 빌드됩니다.

Sphinx는 기술 문서를 작성하는 데 유용한 여러 가지 유용한 기능을 제공하는 신뢰할 수 있는 문서 생성기입니다. - 웹페이지, 인쇄 가능한 PDF, e-리더용 문서 (ePub 등)를 모두 동일한 소스에서 생성합니다. - reStructuredText를 사용하여 문서를 작성할 수 있습니다. - 코드 및 문서를 교차 참조하는 광범위한 시스템. - 구문이 강조 표시된 코드 샘플. - 퍼스트 파티 및 서드 파티 확장 프로그램의 활기찬 생태계

먼저 문서북 형식으로 된 2권의 PCP 도서를 RST 형식으로 변환한 후 REST API 문서를 man 페이지 형식에서 rst 형식으로 변환한 후 pbench 마크다운 콘텐츠를 rst 형식으로 변환한 후 readthedocs 사이트에 모두 호스팅합니다. 확장 목표는 문서의 다이어그램을 개선하는 것입니다.

2.1. reStructuredText 형식으로 변환: 첫 번째 단계는 문서 콘텐츠를 reStructuredText 형식으로 변환하는 것입니다. 각 장에는 별도의 rst 파일이 있으며, 이 파일에는 해당 챕터의 내용만 포함됩니다. 예를 들어 Performance Co-Pilot 사용자 및 관리자 가이드 책에는 8장으로 구성되어 있습니다. 이는 이 8개의 챕터에 해당하는 8개의 서로 다른 rst 파일이 있음을 의미합니다. 향후 혼동을 방지하기 위해 첫 번째 파일의 이름은 챕터 이름과 동일합니다. 그림, 표, 예시 목록은 세 가지 RST 파일에 있습니다. 첫 번째 콘텐츠는 현재와 동일한 방식으로 철저하게 하이퍼링크로 연결됩니다. REST API 문서와 pbench 콘텐츠에도 동일한 내용이 사용됩니다. 굵게, 기울임꼴, 밑줄, 글머리기호, 표, 글꼴 크기, 코드 스타일, 이미지 크기, 정렬 등 필요한 모든 작업은 콘텐츠를 rst 형식으로 변환하는 동안 처리됩니다.

2.2. RST와 Sphinx 통합:

ReadtheDocs는 Sphinx 및 reStructuredText (rst)를 기본값으로 사용합니다. Sphinx가 시스템에 사전 설치되어 있으므로 프로젝트 내에 문서 (Performance Co-Pilot Documentation)를 위한 디렉터리를 만드는 것으로 시작합니다. $ cd /path/to/project $ mkdir docs

그런 다음 거기에서 sphinx-quickstart를 실행합니다. $ cd docs $ sphinx-quickstart

이 빠른 시작에서는 필요한 구성을 만드는 과정을 안내합니다. 대부분의 경우 기본값을 그대로 사용할 수 있지만 필요한 경우 구성 파일에서 중요한 사항을 변경할 수도 있습니다. 완료되면 index.rst, conf.py, 기타 파일이 생성됩니다. index.rst에 Performance Co-Pilot에 관한 모든 필수 세부정보를 추가하고 도서, REST API 문서, pbench 가이드에 관한 제목을 만듭니다. 사용자가 제목을 클릭하면 해당 제목 아래에 있는 모든 문서 자료가 열립니다.

참고: 색인 페이지의 디자인은 멘토와 커뮤니티 구성원의 동의 여부에 따라 결정되며 필요와 요구사항에 따라 변경됩니다.

index.rst는 문서 출력 디렉터리 (일반적으로 _build/html/index.html)의 index.html에 빌드됩니다. Sphinx 문서가 공개 저장소에 저장되면 문서를 가져와 문서 읽기를 사용할 수 있습니다.

문서에 .rst 파일을 추가하면 해당 파일에 대응하는 세 개의 다른 파일이 생성됩니다. 즉, 확장자가 .doctree인 doctrees 폴더에 하나, 확장자가 .html인 HTML 폴더에, 세 번째 파일은 확장자가 .rst.txt인 html/_sources 폴더에 생성됩니다.

  1. 문서 호스팅: 인터넷에 문서를 호스팅하는 작업은 다음 두 단계로 구성됩니다. 1. 문서 가져오기: 먼저 Read The Docs 계정을 GitHub에 연결하고 빌드할 문서 프로젝트를 가져옵니다. 2. 문서 작성: 가져오기 프로세스를 완료한 후 몇 초 이내에 공개 저장소에서 코드를 자동으로 가져오고 문서가 빌드됩니다.

  2. WEBHOOKS: Read the Docs가 문서 및 버전의 변경사항을 감지하는 데 사용하는 기본 방법은 웹훅을 사용하는 것입니다. 웹훅은 GitHub와 같은 저장소 제공업체를 통해 구성되며, 저장소에 대한 커밋, 병합 또는 기타 변경사항이 있을 때마다 Docs 읽기에 알림이 전송됩니다. 웹훅 알림을 받으면 변경사항이 프로젝트의 활성 버전과 관련이 있는지 확인하고, 관련이 있으면 해당 버전에 대해 빌드가 트리거됩니다.

이렇게 하면 모든 사용자 (관리자, 멘토, 커뮤니티 참여자)가 커뮤니티 문서를 변경, 확장 또는 유지할 수 있으며, 문서에 추가되어야 할 내용과 문서에서 삭제해야 하는 내용을 처리하는 데 특정한 제한된 사용자 그룹이 필요하지 않습니다.

  1. 테마: 테마, 레이아웃, 디자인 및 검색과 같은 기타 HTML 기능은 커뮤니티의 요구사항과 가이드라인에 따라 제공됩니다. 커뮤니티 유대감 형성 기간에는 커뮤니티 회원들과 이 모든 사항을 논의할 예정입니다.
  1. 확장 목표: 문서에 있는 다이어그램을 개선해 나갈 것입니다. 현재 다이어그램은 대부분 간단한 흑백 그림입니다. 이미지에 색상, 음영, 크기 조정, 일관성 및 전반적으로 깔끔하고 전문적인 느낌을 더해 보겠습니다.

이를 위해 draw.io (또는 멘토의 동의가 있는 다른 도구)를 사용하겠습니다.

개념 증명으로서, 저는 draw.io를 사용하여 문서에 있는 다이어그램 중 하나를 개선했습니다. 다음 링크에서 확인하세요. https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

개념 증명

PCP 서적의 일부 (문서북 형식)를 첫 번째 형식으로 변환하여 readthedocs 사이트에 호스팅했습니다. 여기에서 확인하세요.

웹사이트 - https://pcp-books.readthedocs.io/en/latest/ 코드 - https://github.com/arzoo14/PCP_Books_Demo

또한 코드 저장소에 웹훅을 구성했는데, 코드 저장소에서 변경한 내용이 웹사이트에 반영됩니다.

일정 및 배송물

커뮤니티 연결 기간[ 2020년 8월 17일~9월 13일 ]

이 시간을 통해 커뮤니티에 익숙해지고, 문서를 살펴보고, 프로세스 초기에 잘못된 결정이 내려지지 않도록 멘토와 여러 사항을 논의할 것입니다. 이 기간 동안 멘토 및 커뮤니티 구성원과 함께 테마, 레이아웃, 디자인, 검색, 탐색 메뉴 등의 기타 기능에 대해 논의합니다. 프로젝트 이름의 결정과 세 가지 주제를 모두 호스팅하기 위한 단일 웹사이트를 사용할지 또는 세 가지 주제에 해당하는 세 개의 각기 다른 웹사이트를 호스팅할지 여부는 커뮤니티 제휴 기간 중에 논의합니다.

문서 개발 기간[ 2020년 9월 14일~11월 30일 ]

***2020년 9월 14일부터 2020년 9월 20일까지 [1주 차] 사용자 및 관리자 가이드 북의 처음 4개 챕터의 문서북 콘텐츠가 첫 번째 형식으로 전환되었습니다.

***2020년 9월 21일부터 2020년 9월 27일까지[2주 차] 사용자 및 관리자 가이드 사진첩의 다음 4개 장에 관한 문서북 콘텐츠가 첫 번째 형식으로 전환되었습니다.

***2020년 9월 28일부터 2020년 10월 4일까지 [3주 차] 프로그래머 가이드 북의 4개 장 전체의 문서북 콘텐츠가 첫 번째 형식으로 전환되었습니다.

***2020년 10월 5일부터 2020년 10월 11일까지 [4주 차] - readthedocs 사이트에 두 PCP 도서 호스팅 - REST API 문서를 man 페이지에서 rst 형식으로 변환 이 기간에는 기본 방문 페이지에 대한 검토가 이루어집니다. - 지난 3주 및 이번 주 블로깅 (내 GSoD 프로젝트)

***2020년 10월 12일부터 2020년 10월 18일까지 [5주 차] 확장 가능한 시계열 색인이 첫 번째 형식으로 전환되었습니다. 확장 가능한 시계열 색인에는 다음이 포함됩니다. GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***2020년 10월 19일부터 2020년 10월 25일까지 [6주 차] PMAPI 호스트 서비스 색인을 RST 형식으로 변환. PMAPI 호스트 서비스 색인에는 GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch , GET /pmapi/children GET /pmapi/indom, GET /pmapi/profile , GET /pmapi/store , GET /pmapi/derive GET /pmapi/metrics가 포함됩니다.

***2020년 10월 26일부터 2020년 11월 1일까지[7주 차] - 지난 몇 주 동안 남아 있는 것이 있는 경우 먼저 처리됩니다. - readthedocs 사이트에 REST API 문서 호스팅 - 지난 2주 및 이번 주 블로깅 (내 GSoD 프로젝트)

***2020년 11월 2일부터 2020년 11월 8일까지[8주 차] pbench 가이드에 사용할 마크다운 콘텐츠를 첫 번째 형식으로 변환했습니다.

***2020년 11월 9일부터 2020년 11월 15일까지 [9주 차] - pbench 가이드를 위해 마크다운 콘텐츠를 첫 번째 형식으로 변환했습니다. - readthedocs 사이트에 pbench 가이드 호스팅 - 지난주 및 이번 주 블로깅 (내 GSoD 프로젝트)

***2020년 11월 16일부터 2020년 11월 22일까지 [10주 차] - 웹사이트의 이름에서 콘텐츠를 검색하기 위한 색인 페이지에 검색 기능을 구현했습니다. - 확장 목표 시작.

***2020년 11월 23일부터 2020년 11월 30일까지 [11주 차] - 문서에 있는 모든 다이어그램을 개선했습니다. - 지난 주와 이번 주의 마지막 블로깅 (내 GSoD 프로젝트) - 코드베이스가 코딩 표준에 부합하는지 확인 그렇지 않은 경우 표준으로 변경합니다.

프로젝트 마감 기간[ 2020년 11월 30일~12월 5일 ]

  • 펜슬 다운타임. 최종 제출을 위해 작업 중이며 문제가 없는지 확인합니다.
  • 프로젝트 보고서 제출(최종 작업 결과물이라고도 함)
  • 프로젝트의 성공 여부 및 멘토와의 실무 경험에 대한 평가서를 제출합니다.