Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.
Tóm tắt dự án
- Tổ chức nguồn mở:
- AboutCode
- Người viết nội dung kỹ thuật:
- ayansinha
- Tên dự án:
- Tài liệu tham khảo về Tuỳ chọn dòng lệnh trong scancode-toolkit và Sắp xếp lại cấu trúc tài liệu AboutCode tại aboutcode.readthedocs.io
- Độ dài dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
[ 1. Tuỳ chọn dòng lệnh của Bộ công cụ mã quét ]
Scancode-Toolkit có một loạt các tuỳ chọn Dòng lệnh để tuỳ chỉnh cách quét, định dạng đầu ra và một số tuỳ chọn khác như trình bổ trợ sau khi quét. Các tuỳ chọn này hiện không có tài liệu thích hợp để giải thích và chỉ có thể sử dụng thông qua cờ "--help" hoặc "-h". Dự án này nhằm mục đích tạo tài liệu hoàn chỉnh giải thích:
[ 1. Tất cả các tuỳ chọn có sẵn thông qua Dòng lệnh ]
- Mục tiêu: Danh sách đầy đủ tất cả tuỳ 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 tuỳ chọn quét mặc định, kèm theo ví dụ về kết quả. Hình ảnh/nội dung mô tả ngắn về cách thực hiện quy trình quét.
Từ giờ trở đi, hành vi mặc định này đóng vai trò là tham chiếu đến cách các tuỳ chọn khác thay đổi quá trình quét và kết quả.
Các thuộc tính này sẽ được thảo luận chi tiết và sẽ chứa các thông tin sau như được đề cập trong các phần tiếp theo.
[ 2. Bắt đầu cấu trúc phiên bản ]
- Mục tiêu: Bắt đầu một hệ thống tạo phiên bản để duy trì đúng cách các thay đổi về tài liệu và API/tuỳ chọn 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 dành cho các bản phát hành cũ và cần được tái cấu trúc lớn.
- Thông tin tổng quan cơ bản: Các phần của bộ công cụ mã quét đã được cập nhật/có thể được cập nhật trong phiên bản này là
- Tuỳ chọn dòng lệnh
- API
- Tài liệu (Sắp được khởi tạo) Các tuỳ chọn dòng lệnh và API được thay đổi trong các phiên bản và bản phát hành, và tài liệu cũng phải tuân theo, nếu không sẽ gây nhầm lẫn lớn cho người dùng. Tiện ích dòng lệnh [ --help ] đã được cập nhật cho mọi thay đổi về tuỳ chọn và có thể được dùng để sao chép phiên bản trong tài liệu.
[ 3. Cách sử dụng các Tuỳ chọn này trong nhiều trường hợp ]
- 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 công cụ quét mã và các tuỳ chọn Công cụ quét mã 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 và các tuỳ chọn được đề xuất trong những tình huống đó.
- Lưu ý: Phần này đòi hỏi sự trợ giúp đáng kể của cố vấn về thông tin đầu vào cũng như gợi ý đến các trường hợp sử dụng Bộ công cụ quét mã.
[ 4. Những thay đổi của các Tuỳ chọn này trong quy 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 công cụ scancode-toolkit trong nhiều trường hợp và các công cụ Aboutcode cung cấp chức năng như vậy.
- Thông tin tổng quan cơ bản: Các tuỳ chọn thay đổi hành vi của cách 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 tuỳ 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 tuỳ chọn mang lại cho trường hợp mặc định này.
[ 5. Định dạng đầu ra và ví dụ về định dạng đó ]
- 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 công cụ scancode-toolkit trong nhiều trường hợp và các công cụ Aboutcode cung cấp chức năng như vậy.
- Thông tin tổng quan cơ bản: Công cụ mã quét có các cờ để chỉ định các định dạng đầu ra khác nhau trong đó kết quả quét sẽ được tạo. Đây là -
Phần này sẽ - giải thích chi tiết về các định dạng đầu ra
- đưa ra ví dụ về đị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 tệp đầu ra. Phần này cũng liên kết đến nội dung Cách tạo các định dạng khác nhau. Nội dung này sẽ được giải thích trong [ 2. Các cuộc thảo luận giải thích tính năng Quét mã ].
[ 6. Việc sử dụng các định dạng đầu ra của mã quét cho doanh nghiệp ]
- Mục tiêu: Giải thích các trường hợp sử dụng kinh doanh của định dạng đầu ra mã quét Trong danh sách ý tưởng về GSoD, Định dạng đầu ra mã quét được đề cập là một ý tưởng tham khảo. Phần này cũng triển khai tương tự.
- Lưu ý: Phần này cần có sự trợ giúp đáng kể của người cố vấn về thông tin đầu vào và các chỉ dẫn đến nhiều trường hợp sử dụng kinh doanh của Bộ công cụ quét mã.
[ 7. Cách các dự án AboutCode khác sử dụng các kết quả này để phân tích thêm ]
- Mục tiêu: Phần này sẽ cung cấp tóm tắt cơ bản về cách sử dụng kết quả quét của bộ công cụ quét mã trong các nguyên nhân khác nhau và công cụ Aboutcode cung cấp chức năng như vậy.
- 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 về scancode-workbench để được hỗ trợ thêm về cùng một vấn đề. 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ả mã 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 về AboutCode ]
Phần này bao gồm một loạt thay đổi đối với Tài liệu về Aboutcode
[ 1. Hệ thống tạo phiên bản ]
Trong [ 1. Tuỳ chọn dòng lệnh của Bộ công cụ mã quét -> 2. Khởi tạo cấu trúc phiên bản] vấn đề tạo phiên bản cho các tuỳ chọn Dòng lệnh được đề cập. Bạn cũng cần làm như vậy đối với các phần khác của tài liệu chứa các lệnh/thông tin dành riêng cho phiên bản có thể gây nhầm lẫn.
[ 2. Thiết lập tiêu chuẩn và kiểm tra cho 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 suốt quá trình) 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. (Được tôi thêm vào Yêu cầu kéo #17 này) Giờ đây, bạn cần kiểm tra thêm để tìm lỗi mã nguồn cụ thể trong Văn bản được tái cấu trúc và các tiêu chuẩn khác. Bạn có thể thực hiện việc 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 dành cho người mới và sẽ chứa một tập hợp các tài liệu cơ bản và quan trọng nhất để bắt đầu với Dự án Aboutcode. Mọi dự án Aboutcode đều có phần này, bao gồm cả Scancode-Toolkit, Scancode-Workbench, Deltacode và các dự án khác.
[ 4. Điều chỉnh cấu trúc theo 4 hàm tài liệu ]
Tài liệu hiện tại không được sắp xếp rõ ràng trong 4 chức năng tài liệu – Hướng dẫn, Cách thực hiện, Tài liệu tham khảo và Giải thích. Tôi đề xuất bạn nên sắp xếp các phần đó cho phù hợp, thêm thông tin/nội dung giải thích/con trỏ nếu cần. Mã này áp dụng cho tất cả các dự án AboutCode và tài liệu của các dự án đó. Dưới đây là hai ví dụ về việc tái cấu trúc tài liệu của Bộ công cụ mã quét mà tôi đề xuất và muốn tiếp tục trong dự án này. Các thay đổi tương tự sẽ được thực hiện đối với phần còn lại của tài liệu.
[ 5. Tái cấu trúc trang 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ễ sử dụng hơn. Có thể có các đường liên kết tới [ 2. Nội dung thảo luận giải thích phần Quét mã ở trên. Điều này liên kết nội dung 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 sử dụng để quét. Giống như các thư mục này chứa nhiều phần của bộ công cụ mã quét, bạn có thể sử dụng riêng các thư mục này bằng API, cùng với phần Thảo luận về cách hoạt động của mã quét.
- [ mã gợi ý : plugin để quét giấy phép, bản quyền, url, email ]
- [ mã chung : lớp và hàm trợ giúp]
- [ extractcode : trích xuất nhiều định dạng lưu trữ ]
- [ formattedcode : định dạng đầu ra cho nhiều định dạng tệp đầu ra ]
- [ licensedcode : licence detection code ]
- [ packagedcode : phân tích cú pháp nhiều định dạng gói ]
- [ plugincode : các lớp cho cấu trúc trình bổ trợ ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : handles text parsing ]
- [ typecode : handles file type determinations ]
- [ scancode : CLI và API để quét mã, phần cốt lõi ]
Tiểu mục này sẽ chứa thông tin/API chi tiết về các phần này của bộ công cụ quét mã trong các tiểu mục tương ứng. Nguyên tắc phát triển sẽ nằm trong một trang khác hoặc một phần khác có các tiểu mục nhỏ hơn.
[ 6. Sắp xếp lại cấu trúc trang Câu hỏi thường gặp (Scancode-Toolkit) ]
Hiện tại, trang Câu hỏi thường gặp có các câu hỏi cần được giải đáp rõ hơn. Do đó, bạn nên xây dựng cấu trúc thành các tài liệu riêng biệt: Tài liệu hướng dẫn, tài liệu hướng dẫn và tài liệu tham khảo.
- Tính năng 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.
- Làm cách nào để 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 bài viết Cải thiện nội dung 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ách riêng nội dung này thành một bài đăng "Cách làm" khác và có thể trình bày chi tiết hơn.
- 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ên trang này trùng lặp khá nhiều. Chúng ta đã thảo luận về việc tái cấu trúc trang phát triển ở trên.
- Các bước để cắt một bản phát hành mới Bạn có thể chuyển đổi nội dung này thành một bài viết riêng có tiêu đề "Cách cắt một bản phát hành mới".
- Tìm thêm các câu hỏi thường gặp giúp trả lời các câu hỏi chung về dự án và không thuộc danh mục "Hướng dẫn"/"Hướng dẫn".