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 Phần Google 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:
brunobeltran
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:
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 string-as-enum ""các loại ngầm ẩn"". Ngoài 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 phải nhập hoặc chi tiết tiền tố giá trị enum thực tế 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)).

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

Vì các kiểu ngầm ẩn này không phải là lớp theo cách riêng, nên Matplotlib trước đây đã 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 __init__ tương ứng).

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

Có thể cho 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 mang 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 sẽ đơn giản là dẫn đến việc chúng ta có ngày càng nhiều bản sao của những tài liệu chi tiết hơn và được lặp lại ở mọi nơi mà từng loại ngầm ẩn này được sử dụng, 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ố họ 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ọ về từng loại ngầm ẩn thông qua việc truyền tải theo kiểu wiki trong tài liệu của chúng tôi, hoặc từng phần trong các ví dụ về StackOverflow, cũng không bền vững.

Mục tiêu kết thúc

Lý tưởng nhất là mọi lượt đề cập đến một kiểu ngầm ẩn nên liên kết đến một trang duy nhất mô tả tất cả các giá trị có thể có mà kiểu đó có thể lấy, đượ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 huyền bí. Thay vì sử dụng không gian trực quan có giá trị trong tài liệu về API cấp cao nhất để liệt kê từng phần tất cả các loại đầ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ừ ngữ thuần tuý về biểu đồ trừu tượng mà tham số dùng để kiểm soát.

Để sử dụng lại ví dụ về linestyle, nội dung chúng ta muố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 dữ liệu đầu vào được phép (kết hợp những dữ liệu có trong Line2D.set_linestyle và hướng dẫn về kiểu dòng).
  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 hiển nhiên từ tên của tham số, nhưng đối với người dùng mới thì không cần phải vậy.

Cách trình bày này trong các 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 hoàn chỉnh, đáng tin cậy về cách Matplotlib xử lý các kiểu đường kẻ.

Lợi ích

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

  1. Làm cho phạm vi đầy đủ của từng hàm có thể hiển thị rõ ràng trong văn bản thuần tuý (không yêu cầu lượt nhấp nào).
  2. Hiển thị tuỳ chọn mặc định (không có lượt nhấp nào). Thông thường, việc chỉ nhìn thấy tuỳ chọn mặc định là đủ để người dùng cũ sử dụng bộ nhớ của mình.
  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 thông số có sẵn dễ dàng trong khi duyệt web (chỉ bằng một lần nhấp).
  4. Giúp quá trình khám phá các tính năng mạnh mẽ hơn và phương thức nhập trở nên dễ dàng như ""cuộn xuống"" để xem thêm các tuỳ chọn nâng cao (vẫn chỉ bằng một lượt nhấp).
  5. Cung cấp một 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 "bài hướng dẫn" liên quan.
  6. Tránh mở rộng API tài liệu, vì việc quét qua nhiều tuỳ chọn có thể cho mỗi tham số sẽ khiến từng tham số khó sử dụng.

Những 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 bị 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"" và ""số liệu") hiện phải học được bằng cách đọc mã.
  3. Quá trình này sẽ làm nổi bật các vấn đề về tính nhất quán của API theo cách có thể dễ dàng theo dõi thông qua công cụ theo dõi lỗi trên GitHub, giúp thúc đẩy quá trình 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ẽ là vô giá. Cách đầu tiên là tạo một trang ""hướng dẫn"" tập trung cho mỗi loại ngầm ẩn. Để làm được điều này, bạn sẽ phải làm việc với nhóm nhà phát triển nòng cốt để xác định danh sách cụ thể các loại ngầm ẩn có tài liệu có giá trị với người dùng (thường vì chúng chứa các tính năng mạnh mẽ, bị ẩn của thư viện mà tài liệu hiện chỉ có trong các hướng dẫn khó tìm thấy). Đối với mỗi loại ngầm ẩn, 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ể được 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 nội dung ngầm ẩn nhất định, nỗ lực lớn thứ hai sẽ bắt đầu: thay thế tài liệu về API hiện có bằng các đường liên kết đến tài liệu mới, hướng tới việc tạo ra trải nghiệm sử dụng thực sự tài liệu mới này dễ dàng nhất có thể, cho cả người dùng tiện ích help() tích hợp sẵn của Python và những người duyệt xem tài liệu của chúng tôi trực tuyến.

Mặc dù định dạng chính xác của các tài liệu được đề 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 nòng cốt Matplotlib trong các ""lệnh gọi nhà phát triển"" hằng tuần của họ để thiết lập sự đồng thuận rằng chiến lược đề xuất ở đây là phương pháp hữu ích, hữu ích và dễ dàng 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ề các lệnh gọi này có sẵn trên bản tấn công). Tôi sẽ sử dụng cơ sở hạ tầng ""hướng dẫn"" hiện có cho các giai đoạn đầu tiên của việc tạo tài liệu tập trung cho từng loại ngầm ẩn, 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 về 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 cốt lõi thống nhất về chiến lược dài hạn tốt nhất để tích hợp tài liệu về ""loại"" 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 ẩn mà tôi đề xuất ghi lại trong Mùa 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ể tìm thấy phiên bản trực tuyến của tài liệu này trên Bài thuyết trình của chúng tôi.