Dự án Đồng thí điểm về hiệu suất

Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần Google Tài liệu.

Tóm tắt dự án

Tổ chức nguồn mở:
Chương trình đồng thí điểm về hiệu suất
Người viết nội dung kỹ thuật:
arzoo14
Tên dự án:
Chuyển đổi nội dung trong dự án sách thành dạng readthedocs (đọc tài liệu) và định dạng reStructureText (Văn bản có cấu trúc) cùng với mục tiêu mở rộng là cải tiến sơ đồ.
Thời lượng dự án:
Thời gian tiêu chuẩn (3 tháng)

Mô tả dự án

TÓM TẮT:

Trang web cộng đồng đóng vai trò thiết yếu trong tổ chức nguồn mở vì nó truyền tải ý tưởng về các dịch vụ mà cộng đồng cung cấp, sự đóng góp quý giá của họ, kỹ năng, tài liệu, hướng dẫn của họ, v.v. Vì vậy, dự án của tôi sẽ hướng đến tăng tính hữu dụng và sự dễ dàng cho tất cả cộng tác viên nguồn mở bằng cách chuyển và cập nhật nội dung sách tài liệu, tài liệu REST và định dạng trang web có thể được lưu trữ trên trang web Dự án này cũng sẽ mang lại lợi ích cho người đóng góp cho cộng đồng bằng cách cho phép họ thay đổi và mở rộng nội dung này dễ dàng hơn. Ngoài ra, với mục tiêu mở rộng, các sơ đồ trong tài liệu sẽ được cải thiện để giao diện chuyên nghiệp hơn.

ĐỀ XUẤT:

  1. TỔNG QUAN: Tài liệu về Performance Co-Experimental ( chương trình thí điểm về hiệu suất) hiện tồn tại ở nhiều định dạng. Những tài liệu này bao gồm sách PCP ở định dạng sách tài liệu, API REST ở định dạng trang chủ và hướng dẫn pbench ở định dạng markdown. Vì vậy, nhóm bảo trì hiện tại của tổ chức đã xác định rằng họ cần một giải pháp ít phải bảo trì nhất có thể, và cho phép cộng đồng nhà phát triển hoàn toàn tập trung vào việc duy trì nội dung của mình theo cách hợp lý và dễ dàng. Do đó, theo nhu cầu hiện tại của tổ chức, tôi sẽ triển khai các mục tiêu sau đây trong Mùa Tài liệu trên Google này:

    1. Chuyển đổi nội dung sách tài liệu sang định dạng reStructureText và lưu trữ nội dung đó trên trang web readthedocs.
    2. Chuyển đổi tài liệu về API REST từ trang chủ sang định dạng thân thiện với nhà phát triển, tức là định dạng reStructureText và lưu trữ tài liệu đó trên trang web readthedocs.
    3. Chuyển đổi nội dung MarkDown trong pbench sang định dạng reStructureText và lưu trữ nội dung đó trên trang web readthedocs.
    4. Mục tiêu kéo dài là để cải thiện các biểu đồ có trong tài liệu.

  2. TRIỂN KHAI: Hiện tại, tài liệu về Performance Co-Experimental (Chương trình đồng thử nghiệm về hiệu suất) không có sẵn ở một định dạng cụ thể. Bất cứ khi nào cần thay đổi nội dung của tài liệu, thì tài liệu đó cần được thay đổi bởi một nhóm người dùng bị hạn chế. Việc thay đổi và mở rộng nội dung của tài liệu không hề dễ dàng đối với những thành viên tích cực trong cộng đồng.

Tôi sẽ giúp tổ chức vượt qua những hạn chế này trong GSoD này với sự trợ giúp của định dạng reStructureText, Đọc tài liệu (RTD) và Sphinx.

Đọc Tài liệu (RTD) giúp đơn giản hoá tài liệu về phần mềm bằng cách tự động hoá việc xây dựng, tạo phiên bản và lưu trữ tài liệu cho chúng tôi. Đây là một nền tảng lưu trữ tài liệu do Sphinx tạo. Giao diện này sử dụng sức mạnh của Sphinx và thêm tính năng quản lý phiên bản, tìm kiếm toàn bộ văn bản và các tính năng hữu ích khác. Công cụ này lấy các tệp mã và tài liệu từ Git, Mercurial hoặc Subversion, sau đó tạo và lưu trữ tài liệu của chúng tôi. Chúng ta sẽ dùng GitHub trong dự án của mình vì đây là hệ thống thường dùng nhất để truy cập mã.

Để bắt đầu, chúng ta sẽ tạo một tài khoản Đọc tài liệu và liên kết tài khoản GitHub. Sau đó, chúng ta sẽ chọn kho lưu trữ GitHub mà chúng ta muốn làm tài liệu, lúc đó điều kỳ diệu sẽ xảy ra.

Việc đọc Tài liệu sẽ: – Sao chép kho lưu trữ của chúng tôi. - Tạo phiên bản HTML, PDF và ePub của tài liệu từ nhánh chính của chúng tôi. – Lập chỉ mục tài liệu của chúng tôi để cho phép tìm kiếm toàn bộ văn bản. – Tạo đối tượng Version (Phiên bản) từ mỗi thẻ và nhánh trong kho lưu trữ. Điều này cũng cho phép chúng tôi lưu trữ các đối tượng đó (không bắt buộc). – Kích hoạt webhook trên kho lưu trữ, để khi đẩy mã đến bất kỳ nhánh nào, tài liệu của chúng ta sẽ được tạo lại.

Sphinx là một trình tạo tài liệu đáng tin cậy có nhiều tính năng tuyệt vời để viết tài liệu kỹ thuật, bao gồm: – Tạo trang web, bản PDF có thể in, tài liệu cho thiết bị đọc sách điện tử (ePub) và nhiều tính năng khác từ cùng một nguồn. – Chúng tôi có thể sử dụng reStructureText để viết tài liệu. – Một hệ thống đa dạng gồm mã tham chiếu chéo và tài liệu. – Mã mẫu được làm nổi bật về cú pháp. – Hệ sinh thái sôi động gồm các tiện ích của bên thứ nhất và bên thứ ba.

Tôi sẽ bắt đầu với việc chuyển đổi hai cuốn sách của PCP có trong định dạng tài liệu sang định dạng đầu tiên, sau việc chuyển đổi tài liệu API REST từ định dạng trang man sang định dạng rst, sau đó chuyển đổi nội dung đánh dấu pbench sang định dạng đầu tiên và cuối cùng, lưu trữ tất cả các nội dung này trên trang web readthedocs. Mục tiêu mở rộng là cải thiện biểu đồ trong tài liệu.

2.1. Chuyển đổi sang định dạng restructureText: Bước đầu tiên là chuyển đổi nội dung tài liệu thành định dạng reStructureText. Mỗi chương sẽ có một tệp đầu tiên riêng, tệp này chỉ chứa nội dung của chương đó. Ví dụ: sách Hướng dẫn dành cho quản trị viên và người dùng tham gia chương trình Đồng thí điểm về hiệu suất gồm 8 chương. Như vậy, sẽ có 8 tệp đầu tiên tương ứng với 8 chương đó. Tên của tệp đầu tiên sẽ giống với tên chương để tránh nhầm lẫn sau này. Danh sách hình, bảng và danh sách ví dụ sẽ có trong ba tệp đầu tiên. Nội dung đầu tiên sẽ hoàn toàn được siêu liên kết theo cách tương tự như nội dung hiện tại. Kiến thức tương tự sẽ được sử dụng cho tài liệu về API REST và nội dung đa phương tiện. Tất cả những việc cần thiết như in đậm, in nghiêng, gạch chân, dấu đầu dòng, bảng, cỡ chữ, kiểu mã, kích thước hình ảnh, căn chỉnh, v.v. sẽ được xử lý trong khi chuyển đổi nội dung sang định dạng đầu tiên.

2.2. Tích hợp rst với Sphinx:

ReadtheDocs sử dụng Sphinx và reconfigureText (đầu tiên) làm giá trị mặc định. Vì Sphinx được cài đặt sẵn trong hệ thống của tôi, nên tôi sẽ bắt đầu bằng việc tạo một thư mục bên trong dự án (có tên là Performance Co-pilot tài liệu) để lưu giữ các tài liệu: $ cd /path/to/project $ mkdir docs

Sau đó, chạy sphinx-Quickstart trong đó: $ cd docs $ sphinx-Quickstart

Bước khởi động nhanh này sẽ hướng dẫn bạn tạo cấu hình cần thiết; trong hầu hết trường hợp, chúng ta có thể chỉ cần chấp nhận các giá trị mặc định (nhưng khi cần, chúng ta có thể thực hiện những thay đổi cần thiết trong tệp cấu hình). Khi quá trình này hoàn tất, chúng ta sẽ có một tệp index.rst, conf.py và một số tệp khác. Trong index.rst, tôi sẽ thêm tất cả thông tin chi tiết cần thiết về Performance Co-pilot và sẽ tạo tiêu đề cho cả sách, tài liệu về API REST và hướng dẫn bỏ lỡ. Khi người dùng nhấp vào một tiêu đề bất kỳ, thao tác này sẽ mở tất cả tài liệu thuộc tiêu đề đó.

LƯU Ý: Thiết kế của trang chỉ mục sẽ dựa theo sự đồng ý của cố vấn và các thành viên trong cộng đồng, đồng thời sẽ thay đổi theo nhu cầu và yêu cầu.

index.rst sẽ được tích hợp vào index.html trong thư mục đầu ra tài liệu của chúng tôi (thường là _build/html/index.html). Sau khi có tài liệu về Sphinx trong kho lưu trữ công khai, chúng ta có thể bắt đầu sử dụng tính năng Đọc tài liệu bằng cách nhập tài liệu của chúng tôi.

Khi chúng ta thêm bất kỳ tệp .rst nào vào tài liệu của mình, tương ứng với tệp đó, ba tệp khác sẽ được tạo, một tệp trong thư mục documenttrees có phần mở rộng .doctree, tệp thứ hai trong thư mục html có phần mở rộng .html và tệp thứ ba trong thư mục html/_sources có phần mở rộng .rst.txt.

  1. LƯU TRỮ TÀI LIỆU: Lưu trữ tài liệu trên Internet bao gồm hai bước: 1. Nhập tài liệu: Bước đầu tiên, tôi sẽ kết nối tài khoản Đọc tài liệu với GitHub và nhập dự án tài liệu của chúng ta để xây dựng. 2. Xây dựng tài liệu: Trong vòng vài giây sau khi hoàn tất quá trình nhập, mã sẽ tự động được tìm nạp từ kho lưu trữ công khai của chúng tôi và tài liệu sẽ được tạo.

  2. WEBHOOKS: Phương thức chính mà tính năng Đọc tài liệu dùng để phát hiện các thay đổi đối với tài liệu và phiên bản là thông qua việc sử dụng webhook. Webhook được định cấu hình thông qua nhà cung cấp kho lưu trữ của chúng tôi, chẳng hạn như GitHub. Với mỗi lệnh cam kết, hợp nhất hoặc một thay đổi khác đối với kho lưu trữ, tính năng Đọc tài liệu sẽ được thông báo. Khi nhận được thông báo về webhook, chúng tôi sẽ xác định xem thay đổi này có liên quan đến một phiên bản đang hoạt động cho dự án hay không. Nếu có, hệ thống sẽ kích hoạt một bản dựng cho phiên bản đó.

Theo đó, tất cả mọi người (quản trị viên, cố vấn, cộng tác viên của cộng đồng) đều có thể thay đổi, mở rộng hoặc duy trì tài liệu về cộng đồng. Đồng thời, không cần một nhóm người dùng cụ thể nào bị hạn chế để xử lý những nội dung được thêm vào tài liệu hoặc nội dung cần bị xoá khỏi tài liệu.

  1. CHỦ ĐỀ: Giao diện, bố cục, thiết kế và các chức năng HTML khác như tìm kiếm sẽ tuân theo nguyên tắc và nhu cầu của cộng đồng. Trong giai đoạn gắn kết cộng đồng, tôi sẽ thảo luận tất cả những điều này với các thành viên trong cộng đồng.
  1. MỤC TIÊU CHUẨN BỊ: Với mục tiêu mở rộng, tôi sẽ cải thiện các sơ đồ có trong tài liệu. Hiện tại, sơ đồ chủ yếu là các hình vẽ đen trắng đơn giản. Tôi sẽ tăng màu sắc, tô bóng, điều chỉnh tỷ lệ, tính nhất quán và giúp hình ảnh trông gọn gàng hơn / chuyên nghiệp hơn.

Để phục vụ mục đích này, tôi sẽ sử dụng draw.io (hoặc bất kỳ công cụ nào khác có sự đồng ý của người cố vấn).

Để chứng minh khái niệm, tôi đã cải thiện một trong các sơ đồ có trong tài liệu với sự trợ giúp của draw.io. Vui lòng tìm bản dịch tại đây: https://docs.google.com/document/d/1CUukNgWH6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

CHỨNG MINH KHÁI NIỆM

Tôi đã chuyển đổi một phần nhỏ của sách PCP (định dạng tài liệu) sang định dạng đầu tiên và lưu trữ nó trên trang web readthedocs. Vui lòng tìm bản dịch tại đây.

Trang web – https://pcp-books.readthedocs.io/en/latest/ Mã – https://github.com/arzoo14/PCP_Books_demo

Nhờ đó, tôi cũng đã định cấu hình webhook trong kho lưu trữ mã. Nhờ đó, những thay đổi thực hiện trong kho lưu trữ mã sẽ được thể hiện trên trang web.

QUÁ TRÌNH VÀ NỘI DUNG CÓ THỂ DÙNG

THỜI GIAN LIÊN KẾT CỘNG ĐỒNG [ Ngày 17 tháng 8 - Ngày 13 tháng 9 năm 2020 ]

Tôi sẽ dành thời gian này để làm quen với cộng đồng, đọc tài liệu và thảo luận nhiều thứ với những người cố vấn để đảm bảo không đưa ra quyết định sai lầm nào trong quá trình này. Tôi sẽ thảo luận với những người cố vấn và các thành viên trong cộng đồng về giao diện, bố cục, thiết kế và các chức năng khác như tìm kiếm, thanh điều hướng, v.v. trong khoảng thời gian này. Quyết định về tên dự án và việc liệu có một trang web duy nhất để lưu trữ cả 3 chủ đề hay 3 trang web tương ứng với 3 chủ đề này sẽ được thảo luận trong giai đoạn gắn kết cộng đồng.

GIAI ĐOẠN PHÁT TRIỂN DOC [ Ngày 14 tháng 9 - Ngày 30 tháng 11 năm 2020 ]

***Từ ngày 14/9/2020 đến ngày 20/9/2020 [TUẦN 1] Chuyển đổi nội dung sách giáo khoa sang định dạng đầu tiên cho 4 chương đầu tiên của sách Hướng dẫn người dùng và quản trị viên.

***Từ ngày 21/9/2020 đến ngày 27/9/2020 [TUẦN 2] Chuyển đổi nội dung sách tài liệu sang định dạng đầu tiên cho 4 chương tiếp theo của sách Hướng dẫn người dùng và quản trị viên.

***Từ ngày 28/9/2020 đến ngày 4/10/2020 [TUẦN 3] Chuyển đổi nội dung sách giáo khoa sang định dạng đầu tiên cho cả 4 chương trong sách Hướng dẫn của Lập trình viên.

***Từ ngày 5 tháng 10 năm 2020 đến ngày 11 tháng 10 năm 2020 [TUẦN 4] – Lưu trữ cả hai cuốn sách của PCP trên trang web readthedocs. – Chuyển đổi tài liệu về API REST từ định dạng man page sang định dạng rst. Trang đích chính sẽ được đề cập trong khoảng thời gian này. – Viết blog (của dự án GSoD) trong ba tuần qua và tuần hiện tại.

***Từ ngày 12/10/2020 đến ngày 18/10/2020 [TUẦN 5] Chuyển đổi chỉ mục Chuỗi thời gian có thể mở rộng sang định dạng rst. Chỉ mục chuỗi thời gian có thể mở rộng bao gồm: GET /loạt/truy vấn , GET /chuỗi/giá trị, GET /loạt/số mô tả , GET /loạt/nhãn, GET /loạt/số liệu , GET /loạt/nguồn , GET /chuỗi/cụm từ , GET /chuỗi/tải

***Từ ngày 19/10/2020 đến ngày 25/10/2020 [TUẦN 6] Chuyển đổi chỉ mục Dịch vụ lưu trữ PMAPI sang định dạng rst. Chỉ mục Dịch vụ lưu trữ PMAPI bao gồm các hoạt động sau: 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

***Từ ngày 26 tháng 10 năm 2020 đến ngày 1 tháng 11 năm 2020 [TUẦN 7] – Nếu còn bất kỳ sự kiện nào trong tuần trước, sự kiện đó sẽ được cung cấp trước. – Lưu trữ tài liệu về API REST trên trang web readthedocs. – Viết blog (của dự án GSoD) trong hai tuần qua và tuần hiện tại.

***Từ ngày 2/11/2020 đến ngày 8/11/2020 [TUẦN 8] Chuyển đổi nội dung đánh dấu sang định dạng đầu tiên cho hướng dẫn trên màn hình.

***Từ ngày 9/11/2020 đến ngày 15/11/2020 [TUẦN 9] – Tiếp tục chuyển đổi nội dung markdown sang định dạng đầu tiên cho hướng dẫn pbench. - Lưu trữ hướng dẫn đọc sách trên trang web readthedocs. – Viết blog (của dự án GSoD) cho tuần trước và tuần hiện tại.

***Từ ngày 16/11/2020 đến ngày 22/11/2020 [TUẦN 10] – Triển khai chức năng tìm kiếm trên trang chỉ mục để tìm kiếm bất kỳ nội dung nào theo tên của nội dung đó trên(các) trang web. – Bắt đầu thực hiện các mục tiêu kéo dài.

***Từ ngày 23 tháng 11 năm 2020 đến ngày 30 tháng 11 năm 2020 [TUẦN 11] – Cải thiện tất cả các biểu đồ có trong tài liệu. – Viết blog cuối cùng (của dự án GSoD) trong tuần vừa qua và tuần hiện tại. – Kiểm tra xem cơ sở mã có đáp ứng các tiêu chuẩn lập trình hay không. Nếu không, hãy thay đổi chúng thành tiêu chuẩn.

THỜI GIAN KẾT THÚC DỰ ÁN [ 30/11 - 5/12/2020 ]

  • Thời gian ngừng hoạt động của bút chì. Đang hoàn tất quá trình gửi cuối cùng và đảm bảo rằng mọi thứ đều ổn.
  • Gửi báo cáo dự án, hay còn gọi là sản phẩm hoàn thiện.
  • Gửi nội dung đánh giá mức độ thành công của các dự án và trải nghiệm làm việc với nhà cố vấn.