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

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

ข้อมูลสรุปของโปรเจ็กต์

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

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

บทคัดย่อ:

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

ข้อเสนอ:

  1. ภาพรวม: ขณะนี้ เอกสารประกอบโปรแกรมนำร่อง Performance Co-Pilot อยู่ในรูปแบบที่แตกต่างกันหลายรูปแบบ ซึ่งรวมถึงหนังสือ PCP ในรูปแบบ DOCP, REST API ในรูปแบบ Manpage และคู่มือ Pbench ในรูปแบบมาร์กดาวน์ กลุ่มผู้ดูแลปัจจุบันขององค์กรจึงระบุว่า องค์กรต้องการโซลูชันที่ไม่ต้องบำรุงรักษามากที่สุดเท่าที่จะเป็นไปได้ และช่วยให้ชุมชนนักพัฒนาซอฟต์แวร์สามารถมุ่งเน้นไปที่การดูแลรักษาเนื้อหาให้คล่องตัวและง่ายที่สุดได้ ดังนั้น ตามความต้องการปัจจุบันขององค์กร ผมจะดำเนินการตามเป้าหมายต่อไปนี้ใน Google ซีซันของเอกสาร นี้:

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

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

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

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

ในการเริ่มต้นใช้งาน เราจะสร้างบัญชีอ่านเอกสาร และลิงก์บัญชี GitHub จากนั้นเราจะเลือกที่เก็บ GitHub ที่ต้องการสร้างเอกสารประกอบ จากนั้นก็จะมีเวทมนตร์ปรากฏขึ้นทันที

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

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

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

2.1. การแปลงเป็นรูปแบบ StructuredText ใหม่: ขั้นตอนแรกคือการแปลงเนื้อหาในเอกสารเป็นรูปแบบ ReStructuredText แต่ละบทจะมีไฟล์ rst แยกต่างหาก ซึ่งจะมีเฉพาะเนื้อหาของบทนั้นๆ ตัวอย่างเช่น หนังสือคู่มือสำหรับผู้ใช้และผู้ดูแลระบบสำหรับ Performance Co-Pilot ประกอบด้วย 8 บท ซึ่งหมายความว่าจะมีไฟล์ rst จำนวน 8 ไฟล์ที่เกี่ยวข้องกับทั้ง 8 บทนั้น ชื่อไฟล์ rst จะเป็นชื่อเดียวกับชื่อบทเพื่อไม่ให้เกิดความสับสนในอนาคต รายการตัวเลข ตาราง และรายการตัวอย่างจะอยู่ในไฟล์ rst 3 ไฟล์ เนื้อหา rst จะมีไฮเปอร์ลิงก์อย่างละเอียดเหมือนกับที่แสดงอยู่ในปัจจุบัน นอกจากนี้ยังใช้แบบเดียวกันนี้ในเอกสาร REST API และเนื้อหา Pbench ระบบจะจัดการทุกสิ่งที่จําเป็น เช่น ตัวหนา ตัวเอียง ขีดเส้นใต้ หัวข้อย่อย ตาราง ขนาดแบบอักษร รูปแบบโค้ด ขนาดรูปภาพ การจัดข้อความ ฯลฯ ในขณะที่แปลงเนื้อหาเป็นรูปแบบ rst

2.2. การผสาน rst กับ Sphinx:

ReadtheDocuments ใช้ Sphinx และ restructText (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 และคำแนะนำในการเปรียบเทียบ เมื่อผู้ใช้คลิกที่ส่วนหัวใดก็ตาม จะเป็นการเปิดเนื้อหาเอกสารทั้งหมดภายใต้หัวข้อนั้น

หมายเหตุ: การออกแบบหน้าดัชนีจะเป็นไปตามความยินยอมของที่ปรึกษาและสมาชิกชุมชน และจะเปลี่ยนแปลงตามความต้องการและข้อกำหนด

index.rst จะถูกสร้างไว้ใน index.html ในไดเรกทอรีเอาต์พุตเอกสารของเรา (โดยทั่วไปคือ _build/html/index.html) เมื่อเรามีเอกสาร Sphinx ในที่เก็บสาธารณะแล้ว เราจะสามารถเริ่มใช้ "อ่านเอกสาร" โดยการนำเข้าเอกสารของเรา

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

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

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

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

  1. ธีม: ธีม เลย์เอาต์ การออกแบบ และฟังก์ชัน HTML อื่นๆ เช่น การค้นหา จะเป็นไปตามความต้องการและหลักเกณฑ์ของชุมชน ในช่วงเวลาสานสัมพันธ์ของชุมชน ฉันจะพูดคุยเรื่องทั้งหมดนี้กับสมาชิกในชุมชน
  1. เป้าหมายสูงสุด: หากมีเป้าหมายเพิ่มเติม ฉันจะปรับปรุงแผนภาพที่มีอยู่ในเอกสารประกอบ ปัจจุบันแผนภาพส่วนใหญ่เป็นภาพวาดขาวดำธรรมดาๆ ผมจะแนะนำการใช้สี การลงสี การปรับสัดส่วน ความสอดคล้อง และการทำให้รูปภาพดูเรียบร้อยขึ้น / ดูเป็นมืออาชีพมากขึ้น

เพื่อให้เป็นไปตามจุดประสงค์นี้ ฉันจะใช้Draw.io (หรือเครื่องมืออื่นๆ ที่ได้รับความยินยอมจากที่ปรึกษา)

เพื่อเป็นการพิสูจน์แนวคิด ฉันได้ปรับปรุงแผนภาพที่มีอยู่ในเอกสารประกอบด้วยความช่วยเหลือของDraw.io โปรดไปที่ https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

หลักฐานแสดงแนวคิด

ฉันได้แปลงส่วนเล็กๆ ของหนังสือ PCP (รูปแบบ Docs) ให้อยู่ในรูปแบบ rst และโฮสต์ไว้ที่ไซต์ readthedocs โปรดดูที่นี่

เว็บไซต์ - https://pcp-books.readthedocs.io/en/latest/ Code - https://github.com/arzoo14/PCP_Books_Demo

ฉันได้กำหนดค่าเว็บฮุคในที่เก็บโค้ดด้วยเพื่อให้ความช่วยเหลือ การเปลี่ยนแปลงที่ทำในที่เก็บโค้ดจะแสดงให้เห็นในเว็บไซต์

ลำดับเวลาและการแสดงโฆษณา

ระยะเวลาผูกมัดของชุมชน [ 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 [สัปดาห์ที่ 3] การแปลงเนื้อหาหนังสือเอกสารเป็นรูปแบบ rst ทั้ง 4 บทของหนังสือคู่มือสำหรับโปรแกรมเมอร์

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

***ตั้งแต่วันที่ 12 ตุลาคม 2020 ถึง 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 พฤศจิกายน 2020 ถึง 8 พฤศจิกายน 2020 [สัปดาห์ที่ 8] การแปลงเนื้อหามาร์กดาวน์ให้เป็นรูปแบบ rst สำหรับคู่มือสำหรับ pbench

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

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

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

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

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