Dự án Matplotlib

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 Google Phần Tài liệu.

Tóm tắt dự án

Tổ chức nguồn mở:
Matplotlib
Người viết nội dung kỹ thuật:
brunorapran
Tên dự án:
Cải thiện khả năng phát hiện tính năng bằng cách chuẩn hoá tài liệu về các loại "ngầm ẩn"
Thời lượng dự án:
Sử dụng lâu dài (5 tháng)

Mô tả dự án

Động lực

Trước đây, API của matplotlib chủ yếu dựa vào ""các kiểu ngầm ẩn"" string-as-enum. Bên cạnh việc bắt chước API của matlab, các chuỗi tham số này cho phép người dùng truyền các giá trị phong phú về ngữ nghĩa dưới dạng đối số đến các hàm matplotlib mà không cần phải nhập rõ ràng hoặc trực tiếp thêm tiền tố giá trị enum thực chỉ để truyền các tuỳ chọn biểu đồ cơ bản (tức là plt.plot(x, y, linestyle='solid') dễ nhập hơn và ít dư thừa hơn so với plt.plot(x, y, linestyle=mpl.LineStyle.solid)).

Từ đó, nhiều loại ngầm định chuỗi dưới dạng enum đã phát triển các tính năng tinh vi hơn. Ví dụ: linestyle hiện có thể ở dạng chuỗi hoặc 2 bộ dữ liệu trình tự, và MarkerStyle hiện có thể là chuỗi hoặc matplotlib.path.Path. Mặc dù điều này đúng với nhiều loại ngầm ẩn, nhưng MarkerStyle là loại duy nhất (theo tôi biết) có trạng thái là đã được nâng cấp lên một lớp Python phù hợp.

Vì các loại ngầm ẩn này không phải là lớp riêng, nên trước đây Matplotlib đã phải triển khai các giải pháp riêng để tập trung tài liệu và xác thực các loại ngầm ẩn này (ví dụ: mẫu nội suy chuỗi tài liệu docstring.interpd.update và mẫu trình xác thực cbook._check_in_list) thay vì sử dụng chuỗi công cụ chuẩn do các lớp Python cung cấp (ví dụ: chuỗi tài liệu và mẫu xác thực tại __init__).

Mặc dù những giải pháp này mang lại hiệu quả, nhưng việc thiếu vị trí rõ ràng để ghi lại từng loại ngầm ẩn đồng nghĩa với việc tài liệu thường rất khó tìm thấy, các bảng lớn gồm các giá trị được phép được lặp lại trong toàn bộ tài liệu và thường thì hoàn toàn không có câu lệnh rõ ràng về phạm vi của một loại ngầm ẩn trong tài liệu. Hãy lấy tài liệu plt.plot làm ví dụ: trong phần ""Notes" ("Ghi chú")", nội dung mô tả về phương thức định kiểu chuỗi định dạng giống như matlab đề cập đến các tuỳ chọn linestyle, color và markers. Có rất nhiều cách để chuyển ba giá trị này so với những gì chúng tôi gợi ý, nhưng đối với nhiều người dùng, đây là nguồn duy nhất để họ hiểu về những giá trị có thể có cho các tuỳ chọn đó cho đến khi họ tình cờ xem một trong những hướng dẫn có liên quan. Bảng thuộc tính Line2D được đưa vào nhằm cho người đọc thấy những tuỳ chọn mà họ có để kiểm soát biểu đồ. Tuy nhiên, mặc dù mục nhập linestyle thực hiện tốt việc liên kết với Line2D.set_linestyle (cần có 2 lượt nhấp) khi mô tả các dữ liệu đầu vào có thể có, còn các mục color và markers thì không. color chỉ liên kết đến Line2D.set_color mà không cung cấp trực quan nào về các loại dữ liệu đầu vào thậm chí còn được phép.

Có thể lập luận rằng đây là vấn đề có thể khắc phục chỉ bằng cách dọn dẹp các chuỗi tài liệu riêng lẻ đang gây ra vấn đề, nhưng rất tiếc là vấn đề này lại có tính hệ thống hơn nhiều. Nếu không có một nơi tập trung để tìm tài liệu, điều này chỉ dẫn đến việc chúng tôi có ngày càng nhiều bản sao của tài liệu chi tiết ngày càng lặp lại ở mọi nơi sử dụng từng loại ngầm ẩn này, khiến người dùng mới bắt đầu đặc biệt khó khăn khi chỉ cần tìm thấy tham số mình cần. Tuy nhiên, hệ thống hiện tại buộc người dùng từ từ kết hợp mô hình tư duy của họ đối với từng loại ngầm định thông qua việc truyền tải theo kiểu mở wiki trong suốt tài liệu của chúng tôi hoặc từng phần từ các ví dụ về StackOverflow, cũng không bền vững.

Kết thúc mục tiêu

Tốt nhất là mọi lượt đề cập đến kiểu ngầm định đều nên liên kết đến một trang mô tả tất cả giá trị có thể có mà kiểu đó có thể nhận, được sắp xếp theo thứ tự từ đơn giản và phổ biến nhất đến nâng cao nhất hoặc bí truyền. Thay vì sử dụng không gian trực quan có giá trị trong tài liệu API cấp cao nhất để liệt kê từng phần tất cả các kiểu đầu vào có thể có cho một tham số cụ thể, chúng ta có thể sử dụng chính không gian đó để cung cấp nội dung mô tả bằng từ đơn giản về mục đích kiểm soát của việc lập biểu đồ trừu tượng.

Để sử dụng lại ví dụ về linestyle, những gì chúng ta cần trong tài liệu LineCollection chỉ là:

  1. Một đường liên kết đến tài liệu hoàn chỉnh cho các thông tin đầu vào được phép (kết hợp các dữ liệu có trong Line2D.set_linestyle và hướng dẫn về kiểu đường kẻ).
  2. Mô tả bằng từ đơn giản về mục đích của tham số. Đối với người dùng thành thạo matplotlib, điều này được thể hiện rõ từ tên của tham số, nhưng đối với người dùng mới thì điều này không cần phải làm như vậy.

Cách trình bày này trong tài liệu thực tế về LineCollection chỉ là python """""" linestyles: `LineStyle` or list thereof, default: :rc:`lines.linestyle` ('-') A description of whether the stroke used to draw each line in the collection is dashed, dotted or solid, or some combination thereof. """""", trong đó tham chiếu loại LineStyle sẽ được Sphinx phân giải để hướng đến một bộ tài liệu duy nhất, đáng tin cậy và hoàn chỉnh về cách Matplotlib xử lý các kiểu đường kẻ.

Lợi ích

Một số tính năng mạnh mẽ của phương pháp này bao gồm

  1. Tạo mức độ đầy đủ về những gì mỗi hàm có thể thể hiện rõ trong văn bản thuần tuý (không cần phải nhấp chuột).
  2. Hiển thị tùy chọn mặc định (không có lượt nhấp nào). Việc chỉ nhìn thấy tuỳ chọn mặc định thường xuyên là đủ để giải phóng bộ nhớ của người dùng cũ.
  3. Tạo nội dung mô tả đầy đủ về các tuỳ chọn ""phổ biến nhất"" và ""dễ nhất"" cho một tham số dễ dàng hiển thị khi duyệt web (bằng một lần nhấp).
  4. Hãy giúp quá trình khám phá các tính năng và phương thức nhập mạnh mẽ hơn trở nên dễ dàng như ""cuộn xuống"" để xem các tuỳ chọn nâng cao hơn (vẫn chỉ một lần nhấp).
  5. Cung cấp chiến lược tập trung để liên kết các tài liệu cấp cao nhất về ""API"" với các ""hướng dẫn" liên quan.
  6. Tránh khai thác API-doc, vì việc quét qua nhiều tuỳ chọn có thể có cho từng tham số sẽ khiến từng tài liệu trở nên khó sử dụng.

Các lợi ích khác của phương pháp này so với các tài liệu hiện tại là:

  1. Tài liệu ít có khả năng trở nên lỗi thời do quá trình tập trung.
  2. Quá trình chuẩn hoá nhiều ""tiêu chuẩn ngầm ẩn"" của matplotlib (như ""giới hạn"" so với ""số liệu"") mà hiện tại phải học bằng cách đọc mã.
  3. Quá trình này sẽ làm nổi bật các vấn đề liên quan đến tính nhất quán của API theo cách dễ dàng hơn để theo dõi thông qua công cụ theo dõi lỗi GitHub, giúp cải thiện API của chúng tôi.
  4. Thời gian tạo tài liệu nhanh hơn do lượng văn bản cần được phân tích cú pháp giảm đáng kể.

Triển khai

Những cải tiến được mô tả ở trên sẽ đòi hỏi hai nỗ lực chính mà một người viết nội dung kỹ thuật chuyên môn sẽ trở nên vô giá. Đầu tiên là tạo một trang ""hướng dẫn"" tập trung cho mỗi kiểu ngầm ẩn. Điều này đòi hỏi phải làm việc với nhóm nhà phát triển cốt lõi để xác định một danh sách cụ thể các loại ngầm ẩn mà tài liệu của họ sẽ có giá trị cho người dùng (thường là vì chúng chứa các tính năng mạnh mẽ, ẩn của thư viện của chúng tôi mà tài liệu hiện chỉ được tìm thấy trong các hướng dẫn mà người dùng khó nắm bắt). Đối với mỗi loại ngầm định, sau đó, tôi sẽ tổng hợp nhiều hướng dẫn, tài liệu API và các trang ví dụ có liên quan thành một nguồn tài liệu đáng tin cậy có thể liên kết đến bất kỳ nơi nào mà loại cụ thể đó được tham chiếu.

Sau khi hoàn tất tài liệu tập trung cho một loại ngầm định nhất định, nỗ lực lớn thứ hai sẽ bắt đầu: thay thế tài liệu API hiện có bằng các đường liên kết đến tài liệu mới nhằm mang lại trải nghiệm thực sự sử dụng tài liệu mới này dễ dàng nhất có thể, cho cả những người sử dụng tiện ích help() tích hợp của Python và những người duyệt tài liệu trực tuyến của chúng tôi.

Mặc dù định dạng chính xác của tài liệu đề xuất ở đây có thể thay đổi khi dự án này phát triển, nhưng tôi đã làm việc với nhóm cốt lõi Matplotlib trong ""cuộc gọi nhà phát triển"" hằng tuần để thiết lập sự đồng thuận rằng chiến lược đề xuất ở đây là cách tiếp cận hợp lý nhất, hữu ích và dễ hiểu về mặt kỹ thuật nhất để bắt đầu ghi lại ""các kiểu ngầm ẩn"" này (ghi chú về những lệnh gọi này có sẵn trên tin tặc). Tôi sẽ sử dụng cơ sở hạ tầng ""thực hành" hiện có cho các giai đoạn đầu của quá trình tạo tài liệu tập trung cho từng kiểu ngầm định, cho phép tôi dễ dàng tham khảo các trang này như sau mà không phải tạo bất kỳ lớp công khai mới nào (xin nhắc lại, hãy dùng tài liệu LineCollection làm ví dụ):

""""""
linestyles: LineStyle or list thereof, default: :rc:`lines.linestyle` ('-')
    A description of whether the stroke used to draw each line in the collection
    is dashed, dotted or solid, or some combination thereof. For a full
    description of possible LineStyle's, see :doc:`tutorials/types/linestyle`.
""""""

Sau đó, chúng tôi có thể dễ dàng thay đổi cách viết các tệp tham chiếu này sau khi nhóm nhà phát triển nòng cốt đồng ý về chiến lược dài hạn tốt nhất để kết hợp tài liệu ""type"" mới của chúng tôi vào các lớp Python thực sự, ví dụ như tôi đề xuất trong Đề xuất nâng cao Matplotlib 30.

Cuối cùng, danh sách sơ bộ các loại ngầm định mà tôi đề xuất ghi lại trong Phần Google Tài liệu này là:

  1. capstyle
  2. joinstyle
  3. bounds
  4. extents
  5. linestyle
  6. colors/lists of colors
  7. colornorm/colormap
  8. tick formatters

Bạn có thể xem phiên bản trực tiếp của tài liệu này trên The Discourse của chúng tôi.