پروژه Co-Pilot عملکرد

این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.

خلاصه ی پروژه

سازمان منبع باز:
عملکرد کمک خلبان
نویسنده فنی:
arzoo14
نام پروژه:
محتوای مناطق پروژه کتاب را به فرمت readthedocs و reStructuredText همراه با هدف توسعه نمودارها تبدیل کنید.
طول پروژه:
طول استاندارد (3 ماه)

شرح پروژه

خلاصه:

یک وب سایت جامعه نقش اساسی در یک سازمان منبع باز ایفا می کند زیرا ایده پیشنهاداتی را که جامعه ارائه می دهد، مشارکت های ارزشمند آنها، مهارت های آنها، مستندات آنها، آموزش های آنها و غیره را گسترش می دهد. بنابراین، هدف پروژه من افزایش قابلیت استفاده است. و سهولت برای همه مشارکت کنندگان منبع باز با انتقال و به روز رسانی محتوای حوزه های پروژه کتاب، به عنوان مثال، محتوای docbook، اسناد REST API و محتوای علامت گذاری pbench به فرمت reStructuredText به طوری که بتوان آن را در سایت مدرن، جامعه readthedocs.io میزبانی کرد. این پروژه همچنین با اجازه دادن به آن‌ها برای تغییر و گسترش آسان‌تر این محتوا، به نفع مشارکت‌کنندگان جامعه خواهد بود. و همچنین، به عنوان یک هدف کششی، نمودارهای موجود در اسناد بهبود می یابند تا ظاهر حرفه ای تری به آنها بدهد.

پیشنهاد:

  1. نمای کلی: مستندات Performance Co-Pilot در حال حاضر در چندین قالب مختلف وجود دارد. اینها شامل کتابهای PCP در فرمت docbook، REST API در قالب manpage و راهنماهای pbench در قالب نشانه گذاری می شود. بنابراین، گروه نگهدارنده فعلی سازمان تشخیص داد که آنها به راه حلی نیاز دارند که تا حد امکان بدون نیاز به تعمیر و نگهداری باشد و به جامعه توسعه دهندگان این امکان را می دهد که کاملاً روی حفظ محتوای خود به روشی ساده و آسان متمرکز شوند. بنابراین، با توجه به نیازهای فعلی سازمان، اهداف زیر را در طول این فصل Google Docs اجرا خواهم کرد:

    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 بر این محدودیت ها غلبه کند.

Read the Docs (RTD) با ساخت خودکار، نسخه‌سازی و میزبانی اسناد ما برای ما، مستندات نرم‌افزار را ساده می‌کند. این یک پلت فرم میزبانی برای اسناد تولید شده توسط Sphinx است. قدرت Sphinx را می گیرد و کنترل نسخه، جستجوی متن کامل و سایر ویژگی های مفید را اضافه می کند. کد و فایل‌های doc را از Git، Mercurial یا Subversion پایین می‌آورد، سپس مستندات ما را می‌سازد و میزبانی می‌کند. ما از GitHub در پروژه خود استفاده خواهیم کرد زیرا این سیستم متداول ترین سیستم برای دسترسی به کد است.

برای شروع، ما یک حساب Read the Docs ایجاد می کنیم و حساب GitHub را پیوند می دهیم. سپس مخزن GitHub را که می‌خواهیم برای آن مستندسازی کنیم، انتخاب می‌کنیم، در این مرحله جادو اتفاق می‌افتد.

اسناد را بخوانید: - مخزن ما را شبیه سازی کنید. - نسخه های HTML، PDF و ePub اسناد ما را از شعبه اصلی ما بسازید. - اسناد ما را فهرست کنید تا امکان جستجوی کامل متن فراهم شود. - اشیاء Version را از هر تگ و شاخه در مخزن خود ایجاد کنید، که به ما امکان می دهد آن ها را نیز به صورت اختیاری میزبانی کنیم. - یک وب هوک را در مخزن خود فعال کنید، بنابراین وقتی کد را به هر شاخه ای فشار می دهیم، اسناد ما بازسازی می شوند.

Sphinx یک تولید کننده مستند معتبر است که دارای بسیاری از ویژگی های عالی برای نوشتن اسناد فنی است، از جمله: - ایجاد صفحات وب، فایل های PDF قابل چاپ، اسناد برای e-readers (ePub) و موارد دیگر از منابع یکسان. - برای نوشتن مستندات می توانیم از reStructuredText استفاده کنیم. - سیستم گسترده ای از کد و مستندات ارجاع متقابل. - نمونه کد هایلایت شده نحوی. - یک اکوسیستم پر جنب و جوش از برنامه های افزودنی شخص ثالث.

من با تبدیل دو کتاب PCP که با فرمت docbook موجود هستند به فرمت rst شروع می کنم، پس از تبدیل مستندات REST API از فرمت man page به فرمت rst، سپس تبدیل محتوای pbench markdown به فرمت rst و در پایان میزبانی همه از اینها در سایت readthedocs. اهداف کششی بهبود نمودارها در مستندات خواهد بود.

2.1. تبدیل به فرمت reStructuredText: اولین قدم تبدیل محتوای اسناد به فرمت reStructuredText خواهد بود. هر فصل دارای یک فایل 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 را در یک مخزن عمومی داریم، می‌توانیم با وارد کردن اسناد خود، از Read the Docs استفاده کنیم.

هنگامی که هر فایل .rst را به مستندات خود اضافه می کنیم، سپس مربوط به آن فایل، سه فایل دیگر ایجاد می شود، یکی در پوشه doctrees با پسوند doctree، دوم در پوشه Html با پسوند html و سومی در html. پوشه /_sources با پسوند rst.txt.

  1. میزبانی اسناد: میزبانی اسناد در اینترنت شامل دو مرحله است: 1. وارد کردن اسناد: در مرحله اول، من حساب Read The Docs را با GitHub متصل می‌کنم و پروژه مستندسازی خود را برای ساخت وارد می‌کنم. 2. ساخت اسناد: ظرف چند ثانیه پس از تکمیل فرآیند واردات، کد به طور خودکار از مخزن عمومی ما دریافت می شود و اسناد ساخته می شوند.

  2. WEBHOOKS: روش اصلی که Read the Docs برای تشخیص تغییرات در اسناد و نسخه ها استفاده می کند، از طریق استفاده از وبکهک ها است. Webhook ها با ارائه دهنده مخزن ما مانند GitHub پیکربندی می شوند و با هر commit، ادغام یا تغییر دیگری در مخزن ما، Read the Docs مطلع می شود. هنگامی که یک اعلان وب هوک دریافت می کنیم، تعیین می کنیم که آیا این تغییر مربوط به یک نسخه فعال برای پروژه ما است یا خیر، و اگر چنین است، یک ساخت برای آن نسخه راه اندازی می شود.

به این ترتیب، هر کسی (مدیران، مربیان، مشارکت کنندگان انجمن) می تواند اسناد انجمن را تغییر دهد، گسترش دهد یا حفظ کند، و هیچ مجموعه محدودی از کاربران برای مراقبت از آنچه باید به اسناد اضافه شود یا آنچه باید از آن حذف شود، مورد نیاز نخواهد بود. مستندات

  1. تم ها: تم ها، طرح ها، طرح ها و سایر قابلیت های HTML مانند جستجو مطابق با نیازها و دستورالعمل های جامعه خواهد بود. در دوره پیوند جامعه، همه اینها را با اعضای جامعه در میان خواهم گذاشت.
  1. SRETCH GOAL: به عنوان یک هدف کششی، نمودارهای موجود در مستندات را بهبود خواهم داد. در حال حاضر، نمودارها عمدتاً نقاشی های سیاه و سفید ساده هستند. من رنگ، سایه، پوسته پوسته شدن، سازگاری و ظاهری مرتب تر/حرفه ای تر را به تصاویر معرفی خواهم کرد.

برای خدمت به این منظور، من از 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

من همچنین وب هوک هایی را در مخزن کد پیکربندی کرده ام که با کمک آنها، تغییرات ایجاد شده در مخزن کد در وب سایت منعکس می شود.

جدول زمانی و موارد تحویل

دوره پیوند جامعه [ 17 اوت - 13 سپتامبر 2020 ]

من این زمان را صرف آشنایی با جامعه، مرور مستندات و بحث در مورد بسیاری از چیزها با مربیان خواهم کرد تا مطمئن شوم هیچ تصمیم بدی در مراحل اولیه گرفته نمی شود. من در این دوره در مورد موضوعات، طرح‌بندی‌ها، طرح‌ها، سایر قابلیت‌ها مانند جستجو، نوار پیمایش و غیره با مربیان و اعضای جامعه بحث خواهم کرد. تصمیم گیری برای نام پروژه و اینکه آیا یک وب سایت واحد برای میزبانی هر سه موضوع وجود خواهد داشت یا سه وب سایت مختلف مربوط به این سه موضوع در طول دوره پیوند جامعه مورد بحث قرار خواهد گرفت.

دوره توسعه DOC [ 14 سپتامبر - 30 نوامبر 2020 ]

***از 14 سپتامبر 2020 تا 20 سپتامبر 2020 [هفته اول] تبدیل محتوای docbook به فرمت rst برای چهار فصل اول کتاب راهنمای کاربران و مدیران.

***از 21 سپتامبر 2020 تا 27 سپتامبر 2020 [هفته دوم] تبدیل محتوای docbook به فرمت rst برای چهار فصل بعدی کتاب راهنمای کاربران و مدیران.

***از 28 سپتامبر 2020 تا 4 اکتبر 2020 [هفته 3] تبدیل محتوای docbook به فرمت rst برای هر چهار فصل کتاب راهنمای برنامه نویس.

***از 5 اکتبر 2020 تا 11 اکتبر 2020 [هفته چهارم] - میزبانی هر دو کتاب PCP در سایت readthedocs. - تبدیل اسناد REST API از صفحه man به فرمت rst. صفحه فرود اصلی در این دوره پوشش داده خواهد شد. - وبلاگ نویسی (پروژه GSoD من) برای سه هفته گذشته و هفته جاری.

***از 12 اکتبر 2020 تا 18 اکتبر 2020 [هفته پنجم] تبدیل فهرست سری زمانی مقیاس پذیر به فرمت rst. شاخص سری زمانی مقیاس پذیر موارد زیر را پوشش می دهد: GET /series/query, GET /series/values, GET /series/descs, GET /series/labels, GET /series/metrics, GET /series/sources, GET /series/instance, 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 [هفته هفتم] - اگر چیزی در هفته های آخر باقی بماند، ابتدا پوشش داده می شود. - میزبانی اسناد REST API در سایت readthedocs. - وبلاگ نویسی (پروژه GSoD من) برای دو هفته گذشته و هفته جاری.

***از 2 نوامبر 2020 تا 8 نوامبر 2020 [هفته 8] تبدیل محتوای علامت گذاری شده به فرمت rst برای راهنماهای pbench.

***از 9 نوامبر 2020 تا 15 نوامبر 2020 [هفته 9] - با تبدیل محتوای نشانه گذاری به فرمت rst برای راهنماهای pbench ادامه یافت. - میزبانی راهنمای pbench در سایت readthedocs. - وبلاگ نویسی (پروژه GSoD من) برای هفته گذشته و هفته جاری.

***از 16 نوامبر 2020 تا 22 نوامبر 2020 [هفته 10] - اجرای قابلیت جستجو در صفحه فهرست برای جستجوی هر محتوایی از نام آن در وب سایت(ها). - شروع اهداف کششی.

***از 23 نوامبر 2020 تا 30 نوامبر 2020 [هفته 11] - بهبود همه نمودارهای موجود در اسناد. - آخرین وبلاگ نویسی (پروژه GSoD من) برای هفته گذشته و هفته جاری. - بررسی اینکه آیا پایگاه کد مطابق با استانداردهای کدنویسی است یا خیر. اگر نه، آنها را به استانداردها تغییر دهید.

دوره نهایی پروژه [ 30 نوامبر - 5 دسامبر 2020 ]

  • زمان از کار افتادن مداد. کار بر روی ارسال نهایی و اطمینان از اینکه همه چیز درست است.
  • ارائه گزارش پروژه که به عنوان محصولات نهایی کار نیز شناخته می شود.
  • ارائه ارزیابی موفقیت پروژه ها و تجربه کاری با مربیان.