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ở:
- AboutCode
- Người viết nội dung kỹ thuật:
- ayansinha
- Tên dự án:
- Tham khảo các Tuỳ chọn dòng lệnh trong bộ công cụ quétcode 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 gian tiêu chuẩn (3 tháng)
Mô tả dự án
[ 1. Tuỳ chọn dòng lệnh quétcode-Toolkit ]
Bộ công cụ quét mã có nhiều 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 lựa chọn này hiện không có tài liệu thích hợp để giải thích và chỉ xuất hiện thông qua cờ “--help” hoặc “-h”. Dự án này nhằm 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ả các tuỳ chọn có thể sử dụng thông qua dòng lệnh.
- Tổng quan cơ bản: Trước tiên, các tuỳ chọn quét mặc định được thảo luận, kèm theo ví dụ về kết quả. Nội dung mô tả/đồ hoạ ngắn về cách thực hiện quá trình quét.
Sau đây, hành vi mặc định này đóng vai trò là mã tham chiếu đến cách các tuỳ chọn khác thay đổi quá trình quét và kết quả.
Nội dung này sẽ được thảo luận chi tiết và trình bày những thông tin sau đây như được đề cập ở các phần tiếp theo.
[ 2. Bắt đầu cấu trúc phiên bản ]
- Mục tiêu: Khởi tạo hệ thống tạo phiên bản để duy trì đúng cách các tuỳ chọn phát hành chéo/các thay đổi về API và tài liệu.
- 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 tái cấu trúc chính.
- Tổng quan cơ bản: Các phần của bộ công cụ quét mã đã được cập nhật/có thể cập nhật trong phiên bản là
- Tuỳ chọn dòng lệnh
- API
- Tài liệu (Cần bắt đầu) 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. Ngoài ra, tài liệu này cũng phải tuân theo, nếu không sẽ gây ra sự 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 đối với tuỳ chọn và có thể được dùng để tái tạo phiên bản trong tài liệu.
[ 3. Cách sử dụng các Tuỳ chọn này trong các trường hợp khác nhau ]
- Mục tiêu: Phần này sẽ đưa ra 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 trong nhiều nguyên nhân và các tuỳ chọn Bộ công cụ quét cung cấp chức năng như vậy.
- Tổng quan cơ bản: Phần này đưa ra các ví dụ về trường hợp sử dụng và những lựa chọn được đề xuất cho những trường hợp đó.
- Lưu ý: Phần này đòi hỏi sự trợ giúp đáng kể của cố vấn về dữ liệu đầu vào và hướng dẫn đến nhiều trường hợp sử dụng Bộ công cụ quét mã.
[ 4. Những Tuỳ chọn này thay đổi trong phần Quét và Đầu ra ]
- 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 trong nhiều mục đích và các công cụ Giới thiệu về cung cấp chức năng như vậy.
- Tổng quan cơ bản: Các tuỳ chọn thay đổi hành vi thực hiện 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 các thay đổi mà tất cả các tuỳ chọn mang đến cho trường hợp mặc định này.
[ 5. Định dạng đầu ra và ví dụ về chúng ]
- 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 trong nhiều mục đích và các công cụ Giới thiệu về cung cấp chức năng như vậy.
- Tổng quan cơ bản: Công cụ quét mã có cờ để chỉ định các định dạng đầu ra khác nhau sẽ tạo kết quả quét. Đây là –
Phần này sẽ - giải thích chi tiết các định dạng đầu ra
- đưa ra ví dụ về các định dạng đầu ra
- cung cấp các liên kết khác tương ứng với định dạng đầu ra và việc sử dụng nó
- cách lưu trữ kết quả quét trong tệp đầu ra. Mục này cũng liên kết đến Cách tạo các định dạng khác nhau. Phần này sẽ được giải thích trong [ 2. Nội dung thảo luận giải thích về tính năng Quét mã ].
[ 6. Sử dụng định dạng đầu ra của mã quét trong doanh nghiệp ]
- Mục tiêu: Giải thích các trường hợp sử dụng định dạng đầu ra mã quét trong kinh doanh Trong danh sách ý tưởng GSoD, định dạng đầu ra mã quét được đề cập đến như một ý tưởng tham khảo. Phần này cũng triển khai theo cách tương tự.
- Lưu ý: Phần này yêu cầu sự trợ giúp đáng kể của cố vấn về thông tin đầu vào và hướng dẫn đến nhiều trường hợp sử dụng Bộ công cụ quét trong doanh nghiệp.
[ 7. Cách các dự án AboutCode khác sử dụng những 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 trong nhiều mục đích và các công cụ Giới thiệu về cung cấp chức năng như vậy.
- Tổng quan cơ bản:
- Quétcode-Workbench Phần này giải thích việc trực quan hoá kết quả bằng ứng dụng dành cho máy tính và con trỏ đến tài liệu quétcode-workbench để được hỗ trợ thêm về cùng một cách. Sẽ thêm tài liệu cần thiết vào scancode-workbench nếu cần.
- Mã 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 giới thiệu về mã ]
Phần này bao gồm một số thay đổi đối với Tài liệu về mã
[ 1. Hệ thống lập phiên bản ]
Trong [ 1. Tuỳ chọn Dòng lệnh Quétcode-Toolkit -> 2. Bắt đầu 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. Điều này cũng cần thiết đối với các phần khác của tài liệu, trong đó chứa thông tin/lệnh cụ thể về 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 tài liệu ]
Tài liệu này đã có các thử nghiệm cho bản dựng logx (xây dựng tất cả các trang và kiểm tra toàn bộ lỗi cú pháp Sphinx) và kiểm tra liên kết (Kiểm tra tất cả các liên kết đến các trang web khác từ tài liệu) với tính năng Tích hợp liên tục thông qua Travis-CI. (Được tôi thêm trong Yêu cầu lấy dữ liệu số 17 này) Giờ đây, công cụ này cần kiểm tra thêm để tìm lỗi mã nguồn cụ thể trong Văn bản có cấu trúc và các tiêu chuẩn khác. Điều này có thể đạt được bằng reStructure-lint nhưng cần được nghiên cứu thêm và sẽ được thực hiện trong dự án GSoD của tôi.
[ 3. Thêm mục “Bắt đầu” ]
Đây sẽ là phần mở đầu cho người mới tham gia, chứa nội dung tổng hợp các tài liệu cơ bản và quan trọng nhất để làm quen với các dự án Aboutcode. Mọi dự án Aboutcode sẽ có phần này, bao gồm cả Quétcode-Toolkit, Quétcode-Workbench, Deltacode và các phần khác.
[ 4. Tái cấu trúc theo 4 chức năng tài liệu ]
Tài liệu hiện có không được trình bày rõ ràng cấu trúc trong 4 chức năng của tài liệu này, đó là: 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 cấu trúc các phần này cho phù hợp, thêm thông tin/giải thích/con trỏ bất cứ khi nào cần thiết. Điều này áp dụng cho tất 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 Quétcode-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 trong phần còn lại của tài liệu.
[ 5. Tái cấu trúc trang phát triển (Bộ công cụ quét mã) ]
Có thể thêm thông tin về Mã/API cho thân thiện hơn với nhà phát triển. Có thể có các đường liên kết đến [ 2. Nội dung thảo luận giải thích về phần Quét mã ] ở trên. Thông tin này sẽ liên kết nội dung giải thích về cách hoạt động của quá trình quét với mã sử dụng để thực hiện quá trình quét. Giống như các thư mục này chứa các phần khác nhau của bộ công cụ quét mã, bạn có thể chi tiết về việc sử dụng riêng các bộ công cụ này cùng với API, kết hợp với 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 : các lớp và hàm trợ giúp]
- [ mã trích xuất : trích xuất các định dạng lưu trữ khác nhau ]
- [ mã định dạng : định dạng đầu ra cho các định dạng tệp đầu ra khác nhau ]
- [ mã được cấp phép : mã phát hiện giấy phép ]
- [ mã đóng gói : phân tích cú pháp các định dạng gói khác nhau ]
- [ plugincode : lớp cho cấu trúc plugin ]
- [ mã tóm tắt : tóm tắt quá trình quét giấy phép được phát hiện ]
- [ mã văn bản : xử lý phân tích cú pháp văn bản ]
- [ mã loại : xử lý xác định loại tệp ]
- [ mã quét : Phần cốt lõi của CLI và API để quét mã ]
Tiểu mục này sẽ chứa thông tin chi tiết/API 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ẽ có trong trang khác hoặc mục khác có tiểu mục nhỏ hơn.
[ 6. Điều chỉnh cấu trúc của 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ó thể được trả lời tốt hơn và nên được cấu trúc thành các tài liệu Hướng dẫn, Hướng dẫn và Tài liệu tham khảo riêng biệt.
- QuétCode 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ề việc Quét mã ] và sẽ là một phần hoàn toàn riêng biệt về nhiều chi tiết hơn.
- Cách thêm quy tắc giấy phép mới cho tính năng Phát hiện nâng cao? Vấn đề này đã được thảo luận trước đó trong phần Cải thiện hướng dẫn hiện có, tài liệu sẽ được chuyển sang đó.
- Cách thêm quy tắc phát hiện giấy phép mới? Bạn có thể làm một bài đăng "Cách thực hiện" khác thành một bài đăng riêng biệt để có thể giải thích cụ thể hơn.
- Làm thế nào để bắt đầu với chương trình Phát triển? Đã có một trang phát triển riêng biệt và thông tin trùng lặp khá nhiều. Việc tái cấu trúc của trang phát triển đã được thảo luận ở trên.
- Các bước cắt bản phát hành mới Bạn có thể chuyển đổi các bước này thành một "Hướng dẫn cắt bản phát hành mới" riêng biệt.
- Tìm thêm các câu hỏi thường gặp giúp trả lời những 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".