Dự án Matplotlib

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ở:
Matplotlib
Người viết nội dung kỹ thuật:
brunobeltran
Tên dự án:
Cải thiện khả năng tìm thấy 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:
Chạy trong thời gian dài (5 tháng)

Mô tả dự án

Động lực

Trước đây, API của matplotlib đã dựa rất nhiều vào ""các loại ngầm ẩn"" chuỗi-là-enum. 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 rõ ràng hoặc thêm tiền tố chi tiết một giá trị enum thực tế chỉ để truyền các tuỳ chọn đồ thị 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 loại ngầm ẩn chuỗi-là-enum này đã phát triển các tính năng phức tạp hơn. Ví dụ: linestyle hiện có thể là một chuỗi hoặc một 2 bộ dữ liệu trình tự và MarkerStyle hiện có thể là một chuỗi hoặc một 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 như tôi biết) có trạng thái đã được nâng cấp lên một lớp Python thích hợp.

Vì các loại ngầm ẩn này không phải là lớp 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 docstring docstring.interpd.update và mẫu trình xác thực cbook._check_in_list, tương ứng) thay vì sử dụng chuỗi công cụ tiêu chuẩn do các lớp Python cung cấp (ví dụ: docstring và mẫu validate-at-__init__, tương ứng).

Mặc dù các giải pháp này đã hoạt động hiệu quả cho chúng tôi, nhưng việc thiếu vị trí rõ ràng để ghi lại từng loại ngầm ẩn có nghĩa là tài liệu thường khó tìm, các bảng lớn về giá trị được phép được lặp lại trong toàn bộ tài liệu và thường thì tài liệu hoàn toàn thiếu tuyên bố rõ ràng về phạm vi của một loại ngầm ẩn. Hãy xem tài liệu về plt.plot, 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ó nhiều cách để truyền ba giá trị này hơn là gợi ý, nhưng đối với nhiều người dùng, đây là nguồn thông tin 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ờ gặp một trong các hướng dẫn liên quan. Bảng thuộc tính Line2D được đưa vào nhằm cố gắng cho người đọc biết họ có những tuỳ chọn nào để kiểm soát biểu đồ của mình. Tuy nhiên, mặc dù mục nhập linestyle liên kết tốt với Line2D.set_linestyle (yêu cầu hai lần nhấp) nơi mô tả các dữ liệu đầu vào có thể có, nhưng mục nhập color và markers thì không. color chỉ liên kết đến Line2D.set_color, không cung cấp trực quan về loại dữ liệu đầu vào được cho phép.

Có thể nói rằng đây là vấn đề có thể khắc phục bằng cách chỉ cần dọn dẹp các docstring riêng lẻ đang gây ra sự cố, nhưng thật không may, vấn đề này 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ẽ chỉ khiến chúng ta có ngày càng nhiều bản sao tài liệu ngày càng dài dòng được lặp lại ở mọi nơi mỗi khi sử dụng các loại ngầm ẩn này, khiến người dùng mới đặc biệt khó tìm thông số họ cần. Tuy nhiên, hệ thống hiện tại buộc người dùng phải từng bước ghép nối mô hình tinh thần của họ về từng loại ngầm ẩn thông qua việc duyệt qua tài liệu theo kiểu wiki hoặc từng phần từ các ví dụ trên StackOverflow cũng không bền vững.

Mục tiêu cuối cùng

Lý tưởng nhất là mọi nội dung đề cập đến một loại ngầm ẩn phải liên kết đến một trang mô tả tất cả các giá trị có thể có của loại đó, được sắp xếp từ đơn giản nhất và phổ biến nhất đến nâng cao nhất hoặc khó hiểu nhất. Thay vì sử dụng không gian hình ảnh có giá trị trong tài liệu API cấp cao nhất để liệt kê từng phần các kiểu dữ liệu đầu vào có thể có cho một tham số cụ thể, thì chúng ta có thể sử dụng chính không gian đó để mô tả từ ngữ đơn giản về việc lập biểu đồ trừu tượng mà tham số sẽ kiểm soát.

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

  1. Đường liên kết đến tài liệu đầy đủ về dữ liệu đầu vào được phép (kết hợp các dữ liệu đầu vào có trong Line2D.set_linestyle và hướng dẫn về kiểu đường).
  2. Nội dung mô tả bằng lời văn đơn giản về mục đích của tham số. Để matplotlib người dùng thành thạo, điều này được thể hiện rõ qua 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 thiết.

Cách hiển thị trong tài liệu LineCollection thực tế 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 để trỏ đến một bộ tài liệu duy nhất, có thẩm quyền và đầy đủ về cách Matplotlib xử lý kiểu đường.

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. Nêu đầy đủ chức năng của mỗi hàm trong văn bản thuần tuý (không yêu cầu lượt nhấp).
  2. Hiển thị tuỳ chọn mặc định (không có lượt nhấp nào). Việc thấy tuỳ chọn mặc định thường là đủ để gợi nhắc người dùng cũ.
  3. Hãy mô tả đầy đủ các tuỳ chọn ""phổ biến nhất"" và ""dễ dàng nhất"" cho một tham số dễ dàng sử dụng khi duyệt xem (chỉ cần một lần nhấp).
  4. 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 chỉ bằng cách ""cuộn xuống"" để xem các tuỳ chọn nâng cao hơn (vẫn chỉ với một lượt nhấp).
  5. Cung cấp chiến lược tập trung để liên kết tài liệu ""API"" cấp cao nhất với ""hướng dẫn"" có liên quan.
  6. Tránh tình trạng API-doc-explosion, trong đó việc quét qua nhiều tuỳ chọn có thể có cho mỗi tham số khiến các chuỗi ký tự riêng lẻ 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 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 được tập trung.
  2. Việc chuẩn hoá nhiều ""tiêu chuẩn ngầm ẩn"" của matplotlib (chẳng hạn như ""bounds"" (giới hạn) khác với ""extents"" (phạm vi)) hiện phải được tìm hiểu bằng cách đọc mã.
  3. Quy 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 dễ theo dõi hơn thông qua trình theo dõi lỗi GitHub, giúp cải thiện API của chúng tôi.
  4. Thời gian xây dựng 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, trong đó một người viết chuyên trách về kỹ thuật 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 cần làm việc với nhóm nhà phát triển cốt lõi để xác định danh sách cụ thể các loại ngầm ẩn có tài liệu hữu ích cho người dùng (thường là vì các loại này chứa các tính năng mạnh mẽ, ẩ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). Đối với mỗi loại ngầm ẩn, tôi sẽ tổng hợp nhiều hướng dẫn, tài liệu API và trang ví dụ có liên quan thành một nguồn tài liệu đáng tin cậy duy nhất 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 ngầm ẩn nhất định, bạn có thể bắt đầu thực hiện nỗ lực lớn thứ hai: 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 mục đích giúp 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ể, cả đối với những người sử dụng tiện ích help() tích hợp sẵn của Python và những người duyệt qua tài liệu của chúng tôi trên mạng.

Mặc dù định dạng chính xác của 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 cốt lõi Matplotlib trong các ""lượt gọi dành cho nhà phát triển"" hằng tuần để thiết lập sự đồng thuận rằng chiến lược được đề xuất ở đây là phương pháp nhanh chóng, hữu ích và dễ xử lý nhất về mặt kỹ thuật để bắt đầu ghi lại những ""loại ngầm ẩn"" này (bạn có thể xem ghi chú về các lệnh gọi này trên hackmd). Tôi sẽ sử dụng cơ sở hạ tầng ""hướng dẫn"" hiện có cho các giai đoạn ban đầu 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 chiếu các trang này như sau mà không cần tạo bất kỳ lớp công khai mới nào (lại sử 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`.
""""""

Từ giờ trở đi, chúng ta 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 đồng ý về chiến lược dài hạn tốt nhất để kết hợp tài liệu ""types"" mới của chúng ta vào các lớp Python chính thống, ví dụ như tôi đã đề xuất trong Đề xuất cải tiến Matplotlib 30.

Cuối cùng, danh sách sơ bộ gồm các loại ngầm ẩn mà tôi đề xuất ghi lại trong Phần Tài liệu này trên Google 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 mới nhất của tài liệu này trên Disourse của chúng tôi.