โปรเจ็กต์นำร่องร่วมด้านประสิทธิภาพ

หน้านี้มีรายละเอียดของโปรเจ็กต์การเขียนเชิงเทคนิคที่ได้รับการยอมรับสำหรับ Google Season of Docs

สรุปโปรเจ็กต์

องค์กรโอเพนซอร์ส:
การนำร่องด้านประสิทธิภาพ
นักเขียนเชิงเทคนิค
arzoo14
ชื่อโปรเจ็กต์:
แปลงเนื้อหาของพื้นที่โปรเจ็กต์หนังสือเป็นรูปแบบ readthedocs และ reStructuredText พร้อมกับเป้าหมายเพิ่มเติมในการปรับปรุงแผนภาพ
ระยะเวลาของโปรเจ็กต์
ระยะเวลามาตรฐาน (3 เดือน)

คำอธิบายโปรเจ็กต์

นามธรรม:

เว็บไซต์ชุมชนมีบทบาทสําคัญในองค์กรโอเพนซอร์ส เนื่องจากเป็นสื่อกลางในการเผยแพร่แนวคิดของข้อเสนอที่ชุมชนมอบให้ ผลงานอันล้ำค่าของชุมชน ทักษะ เอกสารประกอบ บทแนะนํา ฯลฯ ดังนั้น โปรเจ็กต์ของเราจะมุ่งเพิ่มความสามารถในการใช้งานและความสะดวกสําหรับผู้มีส่วนร่วมทุกคนในโอเพนซอร์สโดยการโอนและอัปเดตเนื้อหาของพื้นที่โปรเจ็กต์หนังสือ เช่น เนื้อหา docbook, เอกสารประกอบ REST API และเนื้อหา Markdown ของ pbench ให้เป็นรูปแบบ reStructuredText เพื่อให้โฮสต์บนเว็บไซต์ readthedocs.io สมัยใหม่ของชุมชนได้ โปรเจ็กต์นี้ยังเป็นประโยชน์ต่อผู้มีส่วนร่วมในชุมชนด้วย เนื่องจากช่วยให้ผู้มีส่วนร่วมเปลี่ยนแปลงและขยายเนื้อหานี้ได้ง่ายขึ้น และเราจะปรับปรุงแผนภาพในเอกสารประกอบให้ดูเป็นมืออาชีพมากขึ้นด้วย (เป้าหมายเพิ่มเติม)

PROPOSAL:

  1. ภาพรวม: ปัจจุบันเอกสารประกอบของโปรแกรมสนับสนุนด้านประสิทธิภาพมีให้บริการในรูปแบบต่างๆ ซึ่งรวมถึงสมุด PCP ในรูปแบบเอกสารประกอบแบบ DocBook, REST API ในรูปแบบหน้าคู่มือ และคู่มือ pbench ในรูปแบบ Markdown ดังนั้นกลุ่มผู้ดูแลปัจจุบันขององค์กรจึงพบว่าตนต้องการโซลูชันที่ไม่ต้องบำรุงรักษามากที่สุด และช่วยให้ชุมชนนักพัฒนาแอปมุ่งเน้นที่การดูแลเนื้อหาได้อย่างมีประสิทธิภาพและง่ายดาย ดังนั้น จากความต้องการในปัจจุบันขององค์กร ฉันจะดำเนินการตามเป้าหมายต่อไปนี้ใน Google เอกสารซีซันนี้

    1. การแปลงเนื้อหา DocBook เป็นรูปแบบ reStructuredText และโฮสต์เนื้อหาดังกล่าวในเว็บไซต์ readthedocs
    2. การแปลงเอกสารประกอบของ REST API จาก manpage เป็นรูปแบบที่เหมาะกับนักพัฒนาซอฟต์แวร์ ซึ่งก็คือรูปแบบ restructuredText และโฮสต์ไว้ในเว็บไซต์ Readthedocs
    3. การแปลงเนื้อหา pbench MarkDown เป็นรูปแบบ restructuredText และโฮสต์ไว้ในเว็บไซต์ readthedocs
    4. เป้าหมายเพิ่มเติมคือปรับปรุงแผนภาพที่แสดงในเอกสารประกอบ

  2. การติดตั้งใช้งาน: ปัจจุบันเอกสารประกอบของ Performance Co-Pilot ไม่ได้อยู่ในรูปแบบที่เจาะจง เมื่อใดก็ตามที่จำเป็นต้องเปลี่ยนเนื้อหาของเอกสารประกอบ ผู้ใช้บางกลุ่มจะต้องเปลี่ยนเนื้อหาในเอกสาร ไม่ใช่เรื่องง่ายเลยที่สมาชิกชุมชนที่ใช้งานอยู่จะเปลี่ยนแปลงและขยายเนื้อหาของเอกสาร

เราจะให้องค์กรของคุณเอาชนะข้อจำกัดเหล่านี้ได้ในระหว่าง GSoD นี้ด้วยความช่วยเหลือของรูปแบบ reStructuredText, Read the Docs (RTD) และ Sphinx

อ่านเอกสาร (RTD) เพื่อลดความซับซ้อนของเอกสารประกอบของซอฟต์แวร์ โดยทำให้การสร้าง การกำหนดเวอร์ชัน และโฮสต์เอกสารให้กับเราโดยอัตโนมัติ เป็นแพลตฟอร์มโฮสติ้งสำหรับเอกสารประกอบที่ Sphinx สร้างขึ้น ใช้ความสามารถของ Sphinx และเพิ่มการควบคุมเวอร์ชัน การค้นหาข้อความแบบเต็ม และฟีเจอร์ที่เป็นประโยชน์อื่นๆ โดยจะดึงข้อมูลโค้ดและไฟล์เอกสารจาก Git, Mercurial หรือ Subversion จากนั้นจะสร้างและโฮสต์เอกสารประกอบ เราจะใช้ GitHub ในโปรเจ็กต์เนื่องจากเป็นระบบที่ใช้กันมากที่สุดในการเข้าถึงโค้ด

ในการเริ่มต้นใช้งาน เราจะสร้างบัญชี Read the Docs และลิงก์บัญชี GitHub จากนั้นเราจะเลือกที่เก็บ GitHub ที่ต้องการสร้างเอกสารประกอบ ซึ่งจะเป็นจุดเริ่มต้นของการเปลี่ยนแปลง

Read the Docs จะดำเนินการต่อไปนี้ - โคลนที่เก็บของเรา - สร้างเอกสารประกอบเวอร์ชัน HTML, PDF และ ePub จากสาขาหลัก - จัดทำดัชนีเอกสารของเราเพื่อให้สามารถค้นหาข้อความแบบเต็มได้ - สร้างออบเจ็กต์เวอร์ชันจากแท็กและ Branch แต่ละรายการในที่เก็บของเรา ซึ่งจะช่วยให้เราโฮสต์แท็กและ Branch เหล่านั้นได้ด้วยหากต้องการ - เปิดใช้งาน Webhook ในที่เก็บของเราเพื่อให้ระบบสร้างเอกสารประกอบขึ้นใหม่เมื่อเราพุชโค้ดไปยังสาขาใดก็ตาม

Sphinx เป็นเครื่องมือสร้างเอกสารที่เชื่อถือได้ซึ่งมีฟีเจอร์ที่ยอดเยี่ยมมากมายสำหรับการเขียนเอกสารทางเทคนิค ซึ่งรวมถึงการสร้างหน้าเว็บ, PDF แบบพิมพ์ได้, เอกสารสำหรับโปรแกรมอ่านอีบุ๊ก (ePub) และอื่นๆ จากแหล่งที่มาเดียวกัน - เราใช้ reStructuredText เพื่อเขียนเอกสารประกอบได้ - ระบบการอ้างอิงโค้ดและเอกสารประกอบที่ครอบคลุม - ตัวอย่างโค้ดที่ไฮไลต์ไวยากรณ์ - ระบบนิเวศที่มีชีวิตชีวาของส่วนขยายบุคคลที่หนึ่งและบุคคลที่สาม

เราจะเริ่มต้นด้วยการเปลี่ยนรูปแบบสมุดภาพ PCP 2 เล่มซึ่งมีอยู่ในรูปแบบ docbook เป็นรูปแบบ rst ตามด้วยการเปลี่ยนรูปแบบเอกสารประกอบ REST API จากรูปแบบหน้าคู่มือเป็นรูปแบบ rst จากนั้นเปลี่ยนรูปแบบเนื้อหา Markdown ของ pbench เป็นรูปแบบ rst และสุดท้ายโฮสต์ข้อมูลทั้งหมดนี้ในเว็บไซต์ readthedocs เป้าหมายแบบขยายคือการปรับปรุงแผนภาพในเอกสาร

2.1 การแปลงเป็นรูปแบบ reStructuredText: ขั้นตอนแรกคือการแปลงเนื้อหาเอกสารประกอบเป็นรูปแบบ reStructuredText แต่ละบทจะมีไฟล์ rst แยกกัน ซึ่งจะมีเนื้อหาของบทนั้นๆ เท่านั้น เช่น คู่มือผู้ใช้และผู้ดูแลระบบของ Performance Co-Pilot มี 8 บท ซึ่งหมายความว่าจะมีไฟล์ RSS ที่แตกต่างกัน 8 ไฟล์ที่เกี่ยวข้องกับเนื้อหา 8 บทดังกล่าว ชื่อไฟล์ rst จะเหมือนกับชื่อบทเพื่อไม่ให้เกิดความสับสนในอนาคต รายการรูปภาพ ตาราง และรายการตัวอย่างจะอยู่ในไฟล์ rst 3 ไฟล์ที่แตกต่างกัน เนื้อหาก่อนหน้าจะมีไฮเปอร์ลิงก์อย่างละเอียดในลักษณะเดียวกับที่ทำอยู่ในปัจจุบัน เราจะใช้ชื่อเดียวกันนี้กับเอกสารประกอบของ 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 จะถูกสร้างขึ้นในindex.htmlในไดเรกทอรีเอาต์พุตของเอกสารของเรา (โดยทั่วไปคือ _build/html/index.html) เมื่อเรามีเอกสารประกอบ Sphinx ในที่เก็บข้อมูลสาธารณะแล้ว เราก็จะเริ่มใช้ Read the Docs ได้โดยนำเข้าเอกสาร

เมื่อเราเพิ่มไฟล์ .rst ในเอกสารประกอบ ระบบจะสร้างไฟล์อื่นๆ อีก 3 ไฟล์ซึ่งสอดคล้องกับไฟล์นั้น โดยไฟล์แรกจะอยู่ในโฟลเดอร์ doctrees ที่มีนามสกุล .doctree ไฟล์ที่ 2 จะอยู่ในโฟลเดอร์ Html ที่มีนามสกุล .html และไฟล์ที่ 3 จะอยู่ในโฟลเดอร์ html/_sources ที่มีนามสกุล .rst.txt

  1. โฮสติ้งเอกสารประกอบ: การโฮสติ้งเอกสารประกอบบนอินเทอร์เน็ตประกอบด้วย 2 ขั้นตอนดังนี้ 1. การนําเข้าเอกสารประกอบ: ขั้นตอนแรก เราจะเชื่อมต่อบัญชี Read The Docs กับ GitHub และนําเข้าโปรเจ็กต์เอกสารประกอบเพื่อสร้าง 2. การสร้างเอกสารประกอบ: ภายในไม่กี่วินาทีหลังจากกระบวนการนําเข้าเสร็จสมบูรณ์ ระบบจะดึงข้อมูลโค้ดจากที่เก็บข้อมูลสาธารณะโดยอัตโนมัติและสร้างเอกสารประกอบ

  2. WEBHOOK: วิธีการหลักที่ Read the Docs ใช้ตรวจหาการเปลี่ยนแปลงในเอกสารประกอบและเวอร์ชันคือการใช้ Webhook Webhooks จะได้รับการกําหนดค่ากับผู้ให้บริการที่เก็บ เช่น GitHub และ Read the Docs จะได้รับแจ้งทุกครั้งที่มีการทําคอมมิต ผสาน หรือการเปลี่ยนแปลงอื่นๆ ในที่เก็บของเรา เมื่อได้รับการแจ้งเตือนเว็บฮุค เราจะพิจารณาว่าการเปลี่ยนแปลงนั้นเกี่ยวข้องกับเวอร์ชันที่ใช้งานอยู่สำหรับโปรเจ็กต์ของเราหรือไม่ และหากใช่ ระบบจะทริกเกอร์บิลด์สำหรับเวอร์ชันดังกล่าว

วิธีนี้ช่วยให้ทุกคน (ผู้ดูแลระบบ เมนเทอร์ ผู้มีส่วนร่วมในชุมชน) สามารถเปลี่ยนแปลง ขยาย หรือดูแลรักษาเอกสารประกอบของชุมชนได้ และไม่จำเป็นต้องมีกลุ่มผู้ใช้ที่ถูกจํากัดโดยเฉพาะเพื่อดูแลสิ่งที่ควรเพิ่มลงในเอกสารประกอบหรือสิ่งที่ควรนําออกจากเอกสารประกอบ

  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/en/latest/ โค้ด - https://github.com/arzoo14/PCP_Books_Demo

นอกจากนี้ เรายังได้กําหนดค่า Webhook ในที่เก็บโค้ดด้วย ซึ่งจะช่วยให้การเปลี่ยนแปลงที่ทำในที่เก็บโค้ดแสดงในเว็บไซต์

ไทม์ไลน์และสิ่งที่ส่งมอบ

ระยะเวลาการสร้างชุมชน [ 17 สิงหาคม - 13 กันยายน 2020 ]

เราจะใช้เวลานี้เพื่อทำความคุ้นเคยกับชุมชน อ่านเอกสารประกอบ และพูดคุยกับที่ปรึกษาเกี่ยวกับหลายๆ เรื่อง เพื่อให้แน่ใจว่าจะไม่เกิดการตัดสินใจที่ไม่ถูกต้องในช่วงต้นกระบวนการ ฉันจะหารือเกี่ยวกับธีม เลย์เอาต์ การออกแบบ และฟังก์ชันอื่นๆ เช่น การค้นหา แถบนำทาง ฯลฯ กับที่ปรึกษาและสมาชิกชุมชนในช่วงเวลาดังกล่าว การตัดสินใจเกี่ยวกับชื่อโปรเจ็กต์และจะมีเว็บไซต์เดียวสำหรับโฮสต์หัวข้อทั้ง 3 หัวข้อหรือจะมีเว็บไซต์ 3 เว็บไซต์ที่แตกต่างกันซึ่งสอดคล้องกับหัวข้อทั้ง 3 หัวข้อนั้น จะมีการพูดคุยกันในช่วงการสร้างชุมชน

ระยะเวลาการพัฒนาเอกสาร [ 14 กันยายน - 30 พฤศจิกายน 2020 ]

***ตั้งแต่วันที่ 14 กันยายน 2020 ถึง 20 กันยายน 2020 [สัปดาห์ที่ 1] การแปลงเนื้อหาในสมุดบันทึกเป็นรูปแบบ rst สำหรับ 4 บทแรกของคู่มือคู่มือผู้ใช้และผู้ดูแลระบบ

***ตั้งแต่วันที่ 21 กันยายน 2020 ถึง 27 กันยายน 2020 [สัปดาห์ที่ 2] การแปลงเนื้อหาเอกสารประกอบเป็นรูปแบบ rst สำหรับอีก 4 บทของคู่มือผู้ใช้และผู้ดูแลระบบ

***ตั้งแต่วันที่ 28 กันยายน 2020 ถึง 4 ตุลาคม 2020 [WEEK 3] การแปลงเนื้อหาในสมุดบันทึกเป็นรูปแบบ RST สำหรับทั้ง 4 บทของหนังสือคู่มือโปรแกรมเมอร์

***ตั้งแต่วันที่ 5-11 ตุลาคม 2020 [สัปดาห์ที่ 4] - การโฮสต์หนังสือ PCP ทั้ง 2 เล่มในเว็บไซต์ readthedocs - การแปลงเอกสารประกอบของ REST API จากหน้า man ไปเป็นรูปแบบ rst หน้า Landing Page หลักจะได้รับการคุ้มครองในช่วงเวลานี้ - เขียนบล็อก (เกี่ยวกับโปรเจ็กต์ GSoD) ในช่วง 3 สัปดาห์ที่ผ่านมาและสัปดาห์ปัจจุบัน

***ตั้งแต่วันที่ 12-18 ตุลาคม 2020 [สัปดาห์ที่ 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

***ตั้งแต่วันที่ 19 ตุลาคม 2020 ถึง 25 ตุลาคม 2020 [สัปดาห์ที่ 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

***ตั้งแต่วันที่ 26 ตุลาคม 2020 ถึงวันที่ 1 พฤศจิกายน 2020 [สัปดาห์ที่ 7] - หากยังมีสิ่งใดเหลืออยู่ในช่วงสัปดาห์ที่ผ่านมา เราจะกล่าวถึงกรณีดังกล่าวก่อน - การโฮสต์เอกสาร REST API บนเว็บไซต์ readthedocs - เขียนบล็อก (เกี่ยวกับโปรเจ็กต์ GSoD) ในช่วง 2 สัปดาห์ที่ผ่านมาและสัปดาห์ปัจจุบัน

***ตั้งแต่วันที่ 2-8 พฤศจิกายน 2020 [สัปดาห์ที่ 8] การแปลงเนื้อหา Markdown เป็นรูปแบบ rst สำหรับคู่มือ pbench

***ตั้งแต่วันที่ 9 ถึง 15 พฤศจิกายน 2020 [สัปดาห์ที่ 9] - แปลงเนื้อหา Markdown เป็นรูปแบบ rst สำหรับคู่มือ pbench ต่อ - โฮสติ้งคู่มือ pbench บนเว็บไซต์ readthedocs - เขียนบล็อก (เกี่ยวกับโปรเจ็กต์ GSoD) ของสัปดาห์ที่แล้วและสัปดาห์ปัจจุบัน

***ตั้งแต่วันที่ 16 พฤศจิกายน 2020 ถึงวันที่ 22 พฤศจิกายน 2020 [สัปดาห์ที่ 10] - การใช้งานฟังก์ชันการค้นหาในหน้าดัชนีสำหรับการค้นหาเนื้อหาจากชื่อของเว็บไซต์ในเว็บไซต์ - การเริ่มใช้เป้าหมายที่ท้าทาย

***ตั้งแต่วันที่ 23 พฤศจิกายน 2020 ถึง 30 พฤศจิกายน 2020 [สัปดาห์ที่ 11] - การปรับปรุงแผนภาพทั้งหมดที่มีอยู่ในเอกสารประกอบ - การเขียนบล็อกครั้งสุดท้าย (ของโปรเจ็กต์ GSoD) สำหรับสัปดาห์ที่ผ่านมาและสัปดาห์ปัจจุบัน - ตรวจสอบว่าโค้ดเบสเป็นไปตามมาตรฐานการเขียนโค้ดหรือไม่ หากไม่ ให้เปลี่ยนเป็นมาตรฐาน

ระยะเวลาขั้นสุดท้ายของโครงการ [30 พฤศจิกายน - 5 ธันวาคม 2020 ]

  • ดินสอพักการใช้งาน กำลังดำเนินการกับข้อมูลที่ส่งครั้งสุดท้ายและตรวจสอบว่าทุกอย่างเรียบร้อยดี
  • การส่งรายงานโปรเจ็กต์หรือที่เรียกว่าชิ้นงานขั้นสุดท้าย
  • การส่งการประเมินความสําเร็จของโปรเจ็กต์และประสบการณ์การทำงานร่วมกับที่ปรึกษา