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 tài liệu của Google.
Tóm tắt dự án
- Tổ chức nguồn mở:
- Trình đồng hành 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 của các khu vực dự án sách sang định dạng readthedocs và reStructuredText cùng với mục tiêu cải thiện các sơ đồ.
- Thời lượng dự án:
- Thời hạn 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 một tổ chức nguồn mở vì trang web này truyền bá ý tưởng về các dịch vụ mà cộng đồng cung cấp, những đóng góp quý giá của họ, kỹ năng, tài liệu, hướng dẫn, v.v. Vì vậy, dự án của tôi sẽ hướng đến việc tăng khả năng hữu dụng và dễ dàng cho tất cả những người đóng góp nguồn mở bằng cách chuyển và cập nhật nội dung của các khu vực dự án sách, tức là nội dung sách, tài liệu API REST và nội dung markdown pbench sang định dạng reStructuredText để có thể lưu trữ trên trang web readthedocs.io hiện đại, dành cho cộng đồng. Dự án này cũng sẽ mang lại lợi ích cho những 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, để đạt được mục tiêu mở rộng, sơ đồ trong tài liệu sẽ được cải thiện để trông chuyên nghiệp hơn.
ĐỀ XUẤT:
TỔNG QUAN: Tài liệu về Performance Co-Pilot hiện có ở một số định dạng. Các tài liệu này bao gồm sách PCP ở định dạng sách, API REST ở định dạng trang thông tin và hướng dẫn pbench ở định dạng markdown. Vì vậy, nhóm duy trì hiện tại của tổ chức này nhận thấy rằng họ cần một giải pháp không cần bảo trì càng tốt và cho phép cộng đồng nhà phát triển tập trung hoàn toàn vào việc duy trì nội dung theo cách đơn giản và dễ dàng. Vì vậy, 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 trong Google Season of Docs:
- Chuyển đổi nội dung sách hướng dẫn thành định dạng reStructuredText và lưu trữ nội dung đó trên trang web readthedocs.
- Chuyển đổi tài liệu về API REST từ trang tổng quan sang định dạng phù hợp với nhà phát triển (ví dụ: định dạng restructuredText) và lưu trữ tài liệu đó trên trang web readthedocs.
- Chuyển đổi nội dung pbench MarkDown sang định dạng reStructuredText và lưu trữ nội dung đó trên trang web readthedocs.
- Mục tiêu kéo giãn là để cải thiện các sơ đồ có trong tài liệu.
TRIỂN KHAI: Hiện tại, tài liệu về Performance Co-Pilot không có định dạng cụ thể. Bất cứ khi nào cần thay đổi nội dung của tài liệu, một nhóm người dùng bị hạn chế phải thay đổi nội dung đó. Các thành viên tích cực trong cộng đồng không dễ dàng thay đổi và mở rộng nội dung của tài liệu.
Tôi sẽ giúp tổ chức này khắc phục những hạn chế này trong GSoD này nhờ định dạng reStructuredText, Read the Docs (RTD) và Sphinx.
Read the Docs (RTD) đơn giản hoá tài liệu phần mềm bằng cách tự động tạo, 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. Dịch vụ này sử dụng sức mạnh của Sphinx và bổ sung chức năng quản lý phiên bản, tìm kiếm toàn bộ văn bản cùng các tính năng hữu ích khác. Công cụ này sẽ tải mã và tệp tài liệu xuống 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 vào mã.
Để bắt đầu, chúng ta sẽ tạo một tài khoản Read the Docs 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 tạo tài liệu. Tại thời điểm này, đ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 các phiên bản HTML, PDF và ePub của tài liệu từ nhánh chính. – Lập chỉ mục tài liệu của chúng tôi để cho phép tìm kiếm toàn văn. – Tạo đối tượng Phiên bản từ mỗi thẻ và nhánh trong kho lưu trữ, cho phép chúng ta lưu trữ các đối tượng đó nếu muốn. – Kích hoạt webhook trên kho lưu trữ của chúng tôi để khi chúng tôi đẩy mã đến bất kỳ chi nhánh nào, tài liệu của chúng tôi sẽ được xây dựng lại.
Sphinx là một công cụ tạo tài liệu đáng tin cậy, có nhiều tính năng hữu ích để viết tài liệu kỹ thuật, chẳng hạn như: – Tạo trang web, tệp PDF có thể in, tài liệu cho thiết bị đọc điện tử (ePub) và nhiều tính năng khác từ cùng một nguồn. – Chúng ta có thể sử dụng reStructuredText để viết tài liệu. – Một hệ thống tài liệu và mã tham chiếu chéo mở rộng. – Mã mẫu được đánh dấu cú pháp. – Một hệ sinh thái sinh độ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 bằng cách chuyển đổi hai cuốn sách PCP có định dạng docbook sang định dạng rst, sau khi chuyển đổi tài liệu API REST từ định dạng trang người dùng sang định dạng rst, sau đó chuyển đổi nội dung markdown pbench sang định dạng rst và cuối cùng, lưu trữ tất cả các tài liệu này trên trang web readthedocs. Mục tiêu cao hơn là cải thiện biểu đồ trong tài liệu.
2.1. Chuyển đổi sang định dạng reStructuredText: Bước đầu tiên là chuyển đổi nội dung tài liệu sang định dạng reStructuredText. Mỗi chương sẽ có một tệp rst riêng, chỉ chứa nội dung của chương đó. Ví dụ: Sách hướng dẫn dành cho người dùng và quản trị viên của Performance Co-Pilot bao gồm 8 chương. Điều này có nghĩa là sẽ có 8 tệp rst khác nhau tương ứng với 8 chương đó. Tên của tệp rst sẽ giống với tên chương để tránh nhầm lẫn trong tương lai. Danh sách các hình, bảng và danh sách ví dụ sẽ có trong ba tệp rst khác nhau. Nội dung đầu tiên sẽ được thêm siêu liên kết hoàn toàn giống như cách hiện tại. Điều tương tự cũng sẽ được áp dụng cho tài liệu API REST và nội dung pbench. Tất cả những yếu tố cần thiết, chẳng hạn 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 rst.
2.2. Tích hợp rst với Sphinx:
ReadtheDocs sử dụng Sphinx và reStructuredText (rst) làm 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 Document - Tài liệu đồng thí điểm về hiệu suất) để lưu giữ các tài liệu: $ cd /path/to/project $ mkdir docs
Sau đó, hãy chạy sphinx-quickstart trong đó: $ cd docs $ sphinx-quickstart
Phần bắt đầu 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 các trường hợp, chúng ta 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 các thay đổi cần thiết trong tệp cấu hình). Khi hoàn tất, chúng ta sẽ có 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 API REST và hướng dẫn pbench. Khi người dùng nhấp vào bất kỳ tiêu đề nào, tất cả tài liệu sẽ mở ra trong tiêu đề đó.
LƯU Ý: Thiết kế của trang chỉ mục sẽ được thực hiện theo sự đồng ý của các cố vấn và thành viên cộng đồng, đồng thời sẽ được thay đổi theo nhu cầu và yêu cầu.
index.rst sẽ được tạo thành index.html trong thư mục đầu ra tài liệu của chúng ta (thường là _build/html/index.html). Sau khi có tài liệu Sphinx trong kho lưu trữ công khai, chúng ta có thể bắt đầu sử dụng Read the Docs bằng cách nhập tài liệu.
Khi chúng ta thêm một tệp .rst bất kỳ vào tài liệu, thì tương ứng với tệp đó, hệ thống sẽ tạo 3 tệp khác, một tệp trong thư mục doctrees có đuôi .doctree, thứ hai nằm trong thư mục html có đuôi .html và tệp thứ ba trong thư mục html/_sources có đuôi .rst.txt.
LƯU TRỮ TÀI LIỆU: Việc 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 tôi để xây dựng. 2. Tạo tài liệu: Trong vòng vài giây sau khi hoàn tất quy 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.
WEBHOOK: Phương thức chính mà Read the Docs sử 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à với mỗi lần xác nhận, hợp nhất hoặc thay đổi khác đối với kho lưu trữ của chúng tôi, tính năng Đọc tài liệu sẽ được thông báo. Khi nhận được thông báo webhook, chúng ta sẽ xác định xem thay đổi đó có liên quan đến phiên bản đang hoạt động của dự án hay không. Nếu có, một bản dựng sẽ được kích hoạt cho phiên bản đó.
Bằng cách này, bất kỳ ai (quản trị viên, cố vấn, cộng tác viên cộng đồng) đều có thể thay đổi, mở rộng hoặc duy trì tài liệu cộng đồng. Ngoài ra, không cần có một nhóm người dùng bị hạn chế cụ thể để xử lý những nội dung cần thêm vào hoặc xoá khỏi tài liệu.
- CHỦ ĐỀ: Chủ đề, 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 nhu cầu và nguyên tắc của cộng đồng. Trong giai đoạn gắn kết với 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.
- MỤC TIÊU MỞ RỘNG: Để đạt được 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, các sơ đồ chủ yếu là bản vẽ đơn giản đen trắng. Tôi sẽ giới thiệu thêm màu sắc, độ bóng, tỷ lệ, tính nhất quán và hình ảnh nhìn chung sẽ gọn gàng / 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 khi 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 những sơ đồ có trong tài liệu với sự trợ giúp của Draw.io. Vui lòng xem tại đây: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing
BẰNG CHỨNG VỀ Ý TƯỞNG
Tôi đã chuyển đổi một phần nhỏ của cuốn sách PCP (định dạng docbook) sang định dạng rst và lưu trữ trên trang web readthedocs. Vui lòng xem tại đây.
Trang web – https://pcp-books.readthedocs.io/en/events/ Mã – https://github.com/arzoo14/PCP_Books_demo
Tôi cũng đã định cấu hình webhook trong kho lưu trữ mã với sự trợ giúp của công cụ này. Những thay đổi được thực hiện trong kho lưu trữ mã sẽ được phản ánh trên trang web.
TIẾN TRÌNH VÀ SẢN PHẨM BÀN GIAO
KHOẢNG THỜI GIAN KẾT NỐI 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, xem các tài liệu và thảo luận nhiều điều với người cố vấn để đảm bảo không có quyết định sai lầm nào được đưa ra sớm trong quá trình này. Trong khoảng thời gian này, tôi sẽ thảo luận về các chủ đề, bố cục, thiết kế, các chức năng khác như tìm kiếm, thanh điều hướng, v.v. với các cố vấn và thành viên cộng đồng. Quyết định về tên dự án và việc liệu sẽ có một trang web duy nhất để lưu trữ cả ba chủ đề hay ba trang web khác nhau tương ứng với ba chủ đề sẽ được thảo luận trong giai đoạn gắn kết cộng đồng.
THỜI GIAN PHÁT TRIỂN DOC [Ngày 14 tháng 9 – Ngày 30 tháng 11 năm 2020 ]
***Từ ngày 14 tháng 9 năm 2020 đến ngày 20 tháng 9 năm 2020 [TUẦN 1] Chuyển đổi nội dung sách hướng dẫn thành định dạng rst cho 4 chương đầu tiên của sách Hướng dẫn dành cho người dùng và quản trị viên.
***Từ ngày 21 tháng 9 năm 2020 đến ngày 27 tháng 9 năm 2020 [TUẦN 2] Chuyển đổi nội dung sách hướng dẫn thành định dạng rst cho 4 chương tiếp theo của sách Hướng dẫn dành cho người dùng và quản trị viên.
***Từ ngày 28 tháng 9 năm 2020 đến ngày 4 tháng 10 năm 2020 [TUẦN 3] Chuyển đổi nội dung sách hướng dẫn thành định dạng rst cho cả 4 chương của sách Hướng dẫn 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 PCP trên trang web readthedocs. – Chuyển đổi tài liệu về API REST từ trang man sang định dạng đầu tiên. Trang đích chính sẽ được xem xét trong khoảng thời gian này. – Viết blog (về dự án GSoD của tôi) trong 3 tuần qua và tuần hiện tại.
***Từ ngày 12 tháng 10 năm 2020 đến ngày 18 tháng 10 năm 2020 [TUẦN 5] Chuyển đổi chỉ mục Chuỗi thời gian có thể mở rộng thành đị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 /loạt/giá trị, GET /loạt/mô tả , GET /loạt/nhãn, GET /loạt/số liệu , GET /loạt/nguồn , GET /loạt/thực thể , GET /loạt/tải
***Từ ngày 19 tháng 10 năm 2020 đến ngày 25 tháng 10 năm 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 mục 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 nội dung nào trong những tuần cuối cùng, chúng tôi sẽ đề cập đến nội dung đó trước. – Lưu trữ tài liệu về API REST trên trang web readthedocs. – Viết blog (về dự án GSoD của tôi) trong hai tuần qua và tuần hiện tại.
***Từ ngày 2 tháng 11 năm 2020 đến ngày 8 tháng 11 năm 2020 [TUẦN 8] Chuyển đổi nội dung markdown thành định dạng rst cho hướng dẫn pbench.
***Từ ngày 9 tháng 11 năm 2020 đến ngày 15 tháng 11 năm 2020 [TUẦN 9] – Tiếp tục chuyển đổi nội dung markdown sang định dạng rst cho hướng dẫn pbench. – Lưu trữ hướng dẫn pbench trên trang web readthedocs. – Viết blog (về dự án GSoD của tôi) trong tuần trước và tuần hiện tại.
***Từ ngày 16 tháng 11 năm 2020 đến ngày 22 tháng 11 năm 2020 [TUẦN 10] – Triển khai chức năng tìm kiếm trong trang chỉ mục để tìm kiếm bất kỳ nội dung nào theo tên của nội dung đó trong(các) trang web. – Bắt đầu các mục tiêu mở rộng.
***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ả sơ đồ có trong tài liệu. – Bài đăng cuối cùng (của dự án GSoD) cho tuần trước và tuần hiện tại. – Kiểm tra xem cơ sở mã có tuân thủ 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.
GIAI ĐOẠN KẾT THÚC DỰ ÁN [Ngày 30 tháng 11 – Ngày 5 tháng 12 năm 2020 ]
- Thời gian ngừng hoạt động của Pencil. Làm việc trên bản gửi cuối cùng và đảm bảo mọi thứ đều ổn.
- Gửi báo cáo dự án, còn gọi là sản phẩm công việc cuối cùng.
- Gửi bản đánh giá mức độ thành công của dự án và trải nghiệm làm việc với người cố vấn.