Trang này chứa thông tin chi tiết về một dự án viết tài liệu kỹ thuật được chấp nhận cho Google Season of Docs.
Tóm tắt dự án
- Tổ chức nguồn mở:
- AboutCode
- Chuyên viên viết tài liệu kỹ thuật:
- ayansinha
- Tên dự án:
- Tài liệu tham khảo về các lựa chọn dòng lệnh trong scancode-toolkit và Sắp xếp lại cấu trúc của tài liệu AboutCode tại aboutcode.readthedocs.io
- Thời lượng dự án:
- Thời hạn tiêu chuẩn (3 tháng)
Mô tả dự án
[ 1. Các tuỳ chọn dòng lệnh của Scancode-Toolkit ]
Scancode-Toolkit có nhiều lựa chọn Dòng lệnh để tuỳ chỉnh cách thực hiện quy trình quét, định dạng đầu ra và một số lựa chọn khác như các trình bổ trợ sau khi quét. Hiện tại, các lựa chọn này không có tài liệu phù hợp để giải thích và chỉ có sẵn thông qua cờ "--help" hoặc "-h". Dự án này nhằm mục đích tạo ra tài liệu hoàn chỉnh giải thích:
[ 1. Tất cả các lựa chọn có sẵn thông qua dòng lệnh ]
- Mục tiêu: Một danh sách đầy đủ tất cả các lựa chọn có thể có thông qua dòng lệnh.
- Tổng quan cơ bản: Trước tiên, chúng ta sẽ thảo luận về các lựa chọn quét mặc định, kèm theo ví dụ về đầu ra. Một hình ảnh/nội dung mô tả ngắn gọn về cách thực hiện quy trình quét.
Sau đây, hành vi mặc định này sẽ đóng vai trò là thông tin tham khảo về cách các lựa chọn khác thay đổi quá trình quét và kết quả.
Các thông tin này sẽ được thảo luận chi tiết và sẽ bao gồm những thông tin sau như đã đề cập trong các phần tiếp theo.
[ 2. Khởi tạo cấu trúc quản lý phiên bản ]
- Mục tiêu: Khởi động một hệ thống quản lý phiên bản để duy trì đúng cách các lựa chọn/API và thay đổi về tài liệu trên nhiều bản phát hành.
- Vấn đề: Hiện tại, tài liệu trong wiki và các trang ReadTheDocs là dành cho các bản phát hành cũ và cần được tái cấu trúc đáng kể.
- Tổng quan cơ bản: Các phần của scancode-toolkit đã được cập nhật/có thể được cập nhật trong phiên bản là
- Tuỳ chọn dòng lệnh
- API
- Tài liệu (Sắp được khởi tạo) Các lựa chọn dòng lệnh và API sẽ thay đổi theo các phiên bản và bản phát hành, đồng thời tài liệu cũng phải tuân theo, nếu không, người dùng sẽ rất dễ nhầm lẫn. Tiện ích dòng lệnh [ --help ] đã được cập nhật cho mọi thay đổi về các lựa chọn và có thể được dùng để sao chép việc quản lý phiên bản trong tài liệu.
[ 3. Cách sử dụng các lựa chọn này trong các trường hợp khác nhau ]
- Mục tiêu: Phần này sẽ cung cấp thông tin tóm tắt cơ bản về cách sử dụng kết quả quét của scancode-toolkit trong nhiều trường hợp và các lựa chọn của Scancode-Toolkit cung cấp chức năng đó.
- Thông tin tổng quan cơ bản: Phần này đưa ra các ví dụ về tình huống sử dụng khác nhau và những lựa chọn được đề xuất trong các tình huống đó.
- Lưu ý: Phần này cần có sự trợ giúp đáng kể của người hướng dẫn về thông tin đầu vào và các con trỏ đến nhiều trường hợp sử dụng của Scancode-Toolkit.
[ 4. Những thay đổi này ảnh hưởng đến những gì trong quá trình Quét và Đầu ra
- Mục tiêu: Phần này sẽ cung cấp thông tin tóm tắt cơ bản về cách sử dụng kết quả quét của scancode-toolkit trong nhiều trường hợp và các công cụ Aboutcode cung cấp chức năng đó.
- Thông tin tổng quan cơ bản: Các lựa chọn này thay đổi hành vi của cách thực hiện quy trình quét. Trường hợp mặc định cơ bản sẽ được minh hoạ trong phần đầu [ 1. Tất cả các lựa chọn có sẵn thông qua Dòng lệnh và phần này sẽ so sánh những thay đổi mà tất cả các lựa chọn mang lại cho kịch bản mặc định này.
[ 5. Định dạng đầu ra và ví dụ ]
- Mục tiêu: Phần này sẽ cung cấp thông tin tóm tắt cơ bản về cách sử dụng kết quả quét của scancode-toolkit trong nhiều trường hợp và các công cụ Aboutcode cung cấp chức năng đó.
- Thông tin tổng quan cơ bản: Scancode-Tool có các cờ để chỉ định nhiều định dạng đầu ra mà kết quả quét sẽ được tạo. These are -
This part will - giải thích chi tiết về các định dạng đầu ra
- đưa ra ví dụ về các định dạng đầu ra
- cung cấp các đường liên kết khác tương ứng với định dạng đầu ra và cách sử dụng định dạng đó
- cách lưu trữ kết quả quét trong các tệp đầu ra. Phần này cũng liên kết đến Cách tạo các định dạng này, sẽ được giải thích trong [ 2. Các cuộc thảo luận giải thích về tính năng Quét mã ].
[ 6. Sử dụng cho mục đích kinh doanh đối với Định dạng đầu ra của mã quét ]
- Mục tiêu: Giải thích các trường hợp sử dụng doanh nghiệp của định dạng đầu ra Scancode Trong danh sách ý tưởng GSoD, Định dạng đầu ra Scancode được đề cập đến như một ý tưởng tham khảo. Phần này triển khai điều tương tự.
- Lưu ý: Phần này cần có sự trợ giúp đáng kể của người hướng dẫn về thông tin đầu vào và các điểm tham chiếu đến nhiều trường hợp sử dụng Scancode-Toolkit trong kinh doanh.
[ 7. Cách các đầu ra này được các dự án khác của AboutCode sử dụng để phân tích thêm ]
- Mục tiêu: Phần này sẽ cung cấp thông tin tóm tắt cơ bản về cách sử dụng kết quả quét của scancode-toolkit trong nhiều trường hợp và các công cụ Aboutcode cung cấp chức năng đó.
- Tổng quan cơ bản:
- Scancode-Workbench Phần này giải thích cách trực quan hoá kết quả bằng ứng dụng dành cho máy tính và các con trỏ đến tài liệu scancode-workbench để được hỗ trợ thêm về vấn đề này. Sẽ thêm tài liệu bắt buộc vào scancode-workbench nếu cần.
- Deltacode Cách Deltacode lấy kết quả quét để xác định sự khác biệt ở cấp tệp giữa hai cơ sở mã.
[ 2. Sắp xếp lại cấu trúc của Tài liệu AboutCode ]
Phần này bao gồm một loạt thay đổi đối với Tài liệu Aboutcode
[ 1. Hệ thống lập phiên bản ]
Trong [ 1. Các lựa chọn dòng lệnh của Scancode-Toolkit -> 2. Khởi tạo cấu trúc phân phiên bản] vấn đề phân phiên bản các tuỳ chọn Dòng lệnh được đề cập. Điều này cũng cần thiết cho các phần khác của tài liệu có chứa các lệnh/thông tin dành riêng cho phiên bản, nếu không sẽ gây nhầm lẫn.
[ 2. Thiết lập các tiêu chuẩn và kiểm thử về tài liệu ]
Tài liệu này đã có các bài kiểm thử cho spinx-build (tạo tất cả các trang và kiểm tra lỗi cú pháp Sphinx trong toàn bộ tài liệu) và kiểm tra đường liên kết (Kiểm tra tất cả các đường liên kết đến các trang web khác trong tài liệu) bằng tính năng Tích hợp liên tục thông qua Travis-CI. (Tôi đã thêm vào Yêu cầu kéo này #17 ) Giờ đây, cần có thêm các bước kiểm tra để liên kết cụ thể trong reStructured Text và các tiêu chuẩn khác. Bạn có thể đạt được điều này bằng restructuredtext-lint nhưng cần nghiên cứu thêm và sẽ được thực hiện trong dự án GSoD của tôi.
[ 3. Thêm phần "Bắt đầu" ]
Đây sẽ là phần bắt đầu cho người mới và sẽ chứa một bản tổng hợp các tài liệu cơ bản và quan trọng nhất để bắt đầu với Aboutcode Projects. Mọi dự án của Aboutcode đều có phần này, bao gồm Scancode-Toolkit, Scancode-Workbench, Deltacode và những dự án khác.
[ 4. Tái cấu trúc theo 4 chức năng của tài liệu ]
Tài liệu hiện có không được cấu trúc rõ ràng trong 4 chức năng của tài liệu – Hướng dẫn, Cách thực hiện, Thông tin tham khảo và Giải thích. Tôi đề xuất cấu trúc những phần đó cho phù hợp, đồng thời bổ sung thêm thông tin/giải thích/chỉ dẫn nếu cần. Điều này áp dụng cho tất cả các dự án của AboutCode và tài liệu của các dự án đó. Dưới đây là 2 ví dụ về việc tái cấu trúc tài liệu Scancode-Toolkit mà tôi đề xuất và muốn thực hiện trong dự án này. Những thay đổi tương tự sẽ được thực hiện trên phần còn lại của tài liệu.
[ 5. Tái cấu trúc Trang dành cho nhà phát triển (Scancode-Toolkit) ]
Bạn có thể thêm thông tin khác về Mã/API để giúp nhà phát triển dễ dàng sử dụng hơn. Có thể có các đường liên kết đến [ 2. Các cuộc thảo luận giải thích phần Quét mã ở trên. Thao tác này liên kết phần giải thích về cách hoạt động của quy trình quét với mã mà quy trình này dùng để thực hiện quy trình quét. Giống như các thư mục này chứa nhiều phần của scancode-toolkit, việc sử dụng từng thư mục có thể được trình bày chi tiết bằng các API, cùng với phần Thảo luận về cách hoạt động của scancode.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : extracts different archive formats ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : classes for the plugins architecture ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : handles text parsing ]
- [ typecode : handles file type determinations ]
- [ scancode : CLI and API to scancode, the core part ]
Phần phụ này sẽ chứa thông tin/API chi tiết về các phần này của scancode-toolkit trong các phần phụ tương ứng. Hướng dẫn phát triển sẽ nằm ở một trang khác hoặc một phần khác có các phần nhỏ hơn.
[ 6. Tái cấu trúc trang Câu hỏi thường gặp (Scancode-Toolkit) ]
Trang Câu hỏi thường gặp hiện có những câu hỏi có thể được trả lời tốt hơn và nên được cấu trúc riêng biệt dưới dạng các bài viết riêng về Cách thực hiện, Hướng dẫn và Tài liệu tham khảo.
- ScanCode hoạt động như thế nào? Vấn đề này được đề cập trong [ 2. Các cuộc thảo luận giải thích về tính năng Quét mã và sẽ là một phần hoàn toàn riêng biệt với nhiều thông tin chi tiết hơn.
- Cách thêm quy tắc cấp phép mới để tăng cường khả năng phát hiện? Vấn đề này đã được thảo luận trước đó trong phần Cải thiện các bài viết hướng dẫn hiện có, tài liệu sẽ được chuyển đến đó.
- Cách thêm quy tắc phát hiện giấy phép mới? Bạn có thể tạo một bài đăng "Cách làm" khác riêng biệt và trình bày chi tiết về vấn đề này.
- Làm cách nào để bắt đầu phát triển? Đã có một trang phát triển riêng và thông tin trùng lặp khá nhiều. Chúng tôi đã thảo luận về việc tái cấu trúc trang phát triển ở trên.
- Các bước để phát hành phiên bản mới. Bạn có thể chuyển đổi nội dung này thành một bài viết riêng biệt có tên "Cách phát hành phiên bản mới".
- Tìm thêm các câu hỏi thường gặp trả lời các câu hỏi chung về dự án và không thuộc danh mục "Cách thực hiện"/"Hướng dẫn".