성능 공동 파일럿 프로젝트

이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

오픈소스 구성:
실적 공동조종사
테크니컬 라이터:
arzoo14
프로젝트 이름:
책 프로젝트 영역 콘텐츠를 다이어그램 개선의 연장 목표와 함께 readthedocs 및 reStructuredText 형식으로 변환합니다.
프로젝트 길이:
표준 기간 (3개월)

Project description

개요:

커뮤니티 웹사이트는 커뮤니티가 제공하는 서비스, 그들의 귀중한 기여, 그들의 기술, 문서, 튜토리얼 등을 전파하기 때문에 오픈소스 조직에서 중요한 역할을 합니다. 따라서 본 프로젝트는 도서 프로젝트 영역 콘텐츠를 전송 및 업데이트하여 모든 오픈소스 참여자의 사용성과 편의성을 높이는 것을 목표로 하고 있습니다. 문서, REST API 문서를 최신 커뮤니티 마크다운 형식으로 읽을 수 있습니다. 이 프로젝트는 커뮤니티 참여자가 이 콘텐츠를 더 쉽게 변경하고 확장할 수 있도록 지원하여 커뮤니티 참여자에게도 도움이 됩니다. 문서의 다이어그램을 개선하여 더 전문적인 느낌을 줄 수 있을 뿐만 아니라,

제안서:

  1. 개요: 현재 Performance Co-Pilot 문서는 여러 형식으로 제공됩니다. 여기에는 docbook 형식의 PCP 책, manpage 형식의 REST API, 마크다운 형식의 pbench 가이드가 포함됩니다. 이에 따라 조직의 현재 유지보수자 그룹은 최대한 유지보수가 필요 없는 솔루션과 개발자 커뮤니티가 간편하고 쉬운 방식으로 콘텐츠를 유지하는 데 전념할 수 있는 솔루션이 필요하다고 판단했습니다. 따라서 조직의 현재 요구사항에 따라 이번 Google Docs 시즌 동안 다음 목표를 구현할 것입니다.

    1. docbook 콘텐츠를 reStructuredText 형식으로 변환하고 readthedocs 사이트에 호스팅합니다.
    2. REST API 문서를 manpage에서 개발자 친화적인 형식(예: reStructuredText 형식)으로 변환하고 readthedocs 사이트에 호스팅합니다.
    3. pbench 마크다운 콘텐츠를 reStructuredText 형식으로 변환하고 readthedocs 사이트에 호스팅합니다.
    4. 추가적인 목표는 문서에 있는 다이어그램을 개선하는 것입니다.

  2. 구현: 현재 실적 공동작업자 문서는 특정 형식으로 제공되지 않습니다. 문서 콘텐츠를 변경해야 할 때마다 제한된 사용자 집단이 변경해야 합니다. 활발한 커뮤니티 회원이 문서 콘텐츠를 변경하고 확장하는 것은 쉽지 않습니다.

이번 GSoD에서 reStructuredText 형식, Read the Docs (RTD), Sphinx를 사용하여 조직이 이러한 제한사항을 극복할 수 있도록 지원하겠습니다.

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

시작하려면 Read the Docs 계정을 만들고 GitHub 계정을 연결합니다. 그런 다음 문서를 빌드할 GitHub 저장소를 선택하면 마법이 실행됩니다.

Read the Docs에서 다음 작업을 실행합니다. - 저장소를 클론합니다. - 마스터 브랜치에서 문서의 HTML, PDF, ePub 버전을 빌드합니다. - 전체 텍스트 검색을 허용하도록 문서 색인을 생성합니다. - 저장소의 각 태그 및 브랜치에서 Version 객체를 생성하여 선택적으로 호스팅할 수 있습니다. - 저장소에서 webhook을 활성화하여 코드를 브랜치에 푸시할 때 문서가 다시 빌드되도록 합니다.

Sphinx는 기술 문서 작성을 위한 다양한 유용한 기능을 갖춘 공신력 있는 문서 생성기입니다. 여기에는 다음이 포함됩니다. - 동일한 소스에서 웹페이지, 인쇄 가능한 PDF, 전자책 리더용 문서 (ePub) 등을 모두 생성합니다. - reStructuredText를 사용하여 문서를 작성할 수 있습니다. - 코드 및 문서를 교차 참조하는 광범위한 시스템 - 문법 강조 표시된 코드 샘플 - 퍼스트 파티 및 서드 파티 확장 프로그램의 역동적인 생태계

먼저 docbook 형식의 두 PCP 책을 rst 형식으로 변환한 다음, REST API 문서를 man 페이지 형식에서 rst 형식으로 변환하고, pbench 마크다운 콘텐츠를 rst 형식으로 변환한 후, 마지막으로 readthedocs 사이트에 모두 호스팅합니다. 연장 목표는 문서의 다이어그램을 개선하는 것입니다.

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

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 문서가 있으면 문서를 가져와 Read the Docs를 사용할 수 있습니다.

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

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

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

이렇게 하면 누구나 (관리자, 멘토, 커뮤니티 참여자) 커뮤니티 문서를 변경, 확장 또는 유지할 수 있으며, 문서에 추가해야 할 항목이나 문서에서 삭제해야 할 항목을 처리하기 위해 제한된 특정 사용자 집단이 필요하지 않습니다.

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

이 목적을 위해 draw.io (또는 멘토의 동의를 얻은 다른 도구)를 사용하겠습니다.

개념 증명의 일환으로 draw.io의 도움을 받아 문서에 있는 다이어그램 중 하나를 개선했습니다. 여기에서 확인하세요. https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

개념 증명

PCP 책 (docbook 형식)의 일부를 rst 형식으로 변환하여 readthedocs 사이트에 호스팅했습니다. 여기에서 확인하세요.

웹사이트 - https://pcp-books.readthedocs.io/ko/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개 챕터의 docbook 콘텐츠를 rst 형식으로 변환했습니다.

***2020년 9월 21일~2020년 9월 27일[2주차] 사용자 및 관리자 가이드 책의 다음 4개 챕터의 docbook 콘텐츠를 rst 형식으로 변환합니다.

***2020년 9월 28일~2020년 10월 4일[3주차] 프로그래머 가이드 책의 4개 챕터의 docbook 콘텐츠를 rst 형식으로 변환합니다.

***2020년 10월 5일~2020년 10월 11일[4주차] - readthedocs 사이트에 두 PCP 책 모두 호스팅 - REST API 문서를 man 페이지에서 rst 형식으로 변환했습니다. 이 기간에는 기본 방문 페이지가 적용됩니다. - 지난 3주와 이번 주에 GSoD 프로젝트에 관한 블로그 작성

***2020년 10월 12일~2020년 10월 18일[5주차] 확장형 시계열 색인을 rst 형식으로 변환합니다. 확장 가능한 시계열 색인은 다음을 다룹니다. 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주차]PMDAPI 호스트 서비스 색인을 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 가이드의 Markdown 콘텐츠를 rst 형식으로 변환했습니다.

***2020년 11월 9일~2020년 11월 15일[9주차] - pbench 가이드의 Markdown 콘텐츠를 rst 형식으로 변환하는 작업을 계속했습니다. - readthedocs 사이트에서 pbench 가이드 호스팅 - 지난주와 이번 주의 블로그 (내 GSoD 프로젝트)

***2020년 11월 16일~2020년 11월 22일 [10주차] - 색인 페이지에 웹사이트에서 이름을 통해 콘텐츠를 검색하는 검색 기능을 구현했습니다. - 확장 목표 달성 개시

***2020년 11월 23일~2020년 11월 30일[11주차] - 문서에 있는 모든 다이어그램이 개선되었습니다. - 지난주와 이번주에 대한 (GSoD 프로젝트의) 최종 블로그 게시 - 코드베이스가 코딩 표준을 따르는지 확인 그렇지 않은 경우 표준으로 변경합니다.

프로젝트 최종 결정 기간[ 2020년 11월 30일~12월 5일 ]

  • 연필을 멈출 수 있습니다. 최종 제출 작업 중 아무 문제가 없는지 확인합니다.
  • 최종 작업물이라고도 하는 프로젝트 보고서 제출
  • 프로젝트 성공에 대한 평가 및 멘토와의 작업 경험을 제출합니다.