Một chuỗi tài liệu Python là một chuỗi được sử dụng để ghi lại một mô-đun, lớp, hàm hoặc phương thức Python, vì vậy các lập trình viên có thể hiểu nó làm gì mà không cần phải đọc chi tiết về cách triển khai Show Ngoài ra, thực tế phổ biến là tự động tạo tài liệu trực tuyến (html) từ chuỗi tài liệu. Nhân sư phục vụ mục đích này Ví dụ tiếp theo đưa ra ý tưởng về một chuỗi tài liệu trông như thế nào def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num2 Một số tiêu chuẩn liên quan đến chuỗi tài liệu tồn tại, giúp chúng dễ đọc hơn và cho phép dễ dàng xuất chúng sang các định dạng khác như html hoặc pdf Các quy ước đầu tiên mà mọi chuỗi tài liệu Python phải tuân theo được xác định trong PEP-257 Vì PEP-257 khá rộng nên các tiêu chuẩn khác cụ thể hơn cũng tồn tại. Trong trường hợp gấu trúc, quy ước chuỗi tài liệu NumPy được tuân theo. Các quy ước này được giải thích trong tài liệu này
numpydoc là một tiện ích mở rộng của Sphinx để hỗ trợ quy ước chuỗi tài liệu NumPy Tiêu chuẩn sử dụng reStructuredText (reST). reStructuredText là ngôn ngữ đánh dấu cho phép mã hóa các kiểu trong tệp văn bản thuần túy. Tài liệu về reStructuredText có thể được tìm thấy trong
gấu trúc có một số người trợ giúp để chia sẻ tài liệu giữa các lớp liên quan, xem Phần còn lại của tài liệu này sẽ tóm tắt tất cả các hướng dẫn ở trên và sẽ cung cấp các quy ước bổ sung dành riêng cho dự án gấu trúc Viết một chuỗi tài liệuquy tắc chungCác tài liệu phải được xác định bằng ba dấu ngoặc kép. Không được để trống dòng nào trước hoặc sau chuỗi tài liệu. Văn bản bắt đầu ở dòng tiếp theo sau dấu ngoặc kép mở đầu. Các trích dẫn kết thúc có dòng riêng (có nghĩa là chúng không ở cuối câu cuối cùng) Trong một số trường hợp hiếm hoi, các kiểu còn lại như văn bản in đậm hoặc in nghiêng sẽ được sử dụng trong tài liệu, nhưng thường có mã nội tuyến, được trình bày giữa các dấu gạch ngược. Sau đây được coi là mã nội tuyến
Ghi chú Để chỉ hiển thị thành phần cuối cùng của lớp, phương thức hoặc chức năng được liên kết, hãy đặt tiền tố cho nó bằng def astype(dtype): """ Cast Series type. This section will provide further details. """ pass6. Ví dụ: def astype(dtype): """ Cast Series type. This section will provide further details. """ pass7 sẽ liên kết đến def astype(dtype): """ Cast Series type. This section will provide further details. """ pass8 nhưng chỉ hiển thị phần cuối cùng, def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9 dưới dạng văn bản liên kết. Xem để biết chi tiết Tốt def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar3 Xấu def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar Phần 1. tóm tắt ngắnTóm tắt ngắn gọn là một câu duy nhất diễn đạt những gì chức năng thực hiện một cách ngắn gọn Tóm tắt ngắn phải bắt đầu bằng chữ in hoa, kết thúc bằng dấu chấm và nằm trong một dòng. Nó cần thể hiện những gì đối tượng làm mà không cung cấp chi tiết. Đối với các hàm và phương thức, phần tóm tắt ngắn phải bắt đầu bằng một động từ nguyên thể Tốt def astype(dtype): """ Cast Series type. This section will provide further details. """ pass Xấu def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar6 def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar7 def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar8 def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar9 Phần 2. tóm tắt mở rộngTóm tắt mở rộng cung cấp chi tiết về những gì chức năng làm. Nó không nên đi sâu vào chi tiết của các thông số, hoặc thảo luận về ghi chú thực hiện, mà sẽ đi vào các phần khác Một dòng trống được để lại giữa phần tóm tắt ngắn và phần tóm tắt mở rộng. Mỗi đoạn trong phần tóm tắt mở rộng đều kết thúc bằng dấu chấm Phần tóm tắt mở rộng sẽ cung cấp chi tiết về lý do tại sao chức năng này hữu ích và các trường hợp sử dụng của chúng, nếu nó không quá chung chung def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar0 Phần 3. thông sốChi tiết các tham số sẽ được bổ sung trong phần này. Phần này có tiêu đề "Tham số", theo sau là một dòng có dấu gạch ngang dưới mỗi chữ cái của từ "Tham số". Một dòng trống được để lại trước tiêu đề của phần, nhưng không phải sau và không phải giữa dòng có từ "Tham số" và dòng có dấu gạch nối Sau tiêu đề, mỗi tham số trong chữ ký phải được ghi lại, bao gồm def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar60 và def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar61, nhưng không phải def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar62 Các tham số được xác định theo tên của chúng, theo sau là khoảng trắng, dấu hai chấm, dấu cách khác và loại (hoặc các loại). Lưu ý rằng khoảng cách giữa tên và dấu hai chấm rất quan trọng. Các loại không được xác định cho def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar60 và def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar61, nhưng phải được xác định cho tất cả các tham số khác. Sau phần định nghĩa tham số bắt buộc phải có một dòng mô tả tham số, được thụt vào trong, có thể có nhiều dòng. Mô tả phải bắt đầu bằng chữ in hoa và kết thúc bằng dấu chấm Đối với các đối số từ khóa có giá trị mặc định, giá trị mặc định sẽ được liệt kê sau dấu phẩy ở cuối loại. Hình thức chính xác của loại trong trường hợp này sẽ là "int, default 0". Trong một số trường hợp, có thể hữu ích khi giải thích ý nghĩa của đối số mặc định, có thể được thêm vào sau dấu phẩy "int, default -1, có nghĩa là tất cả cpus" Trong trường hợp giá trị mặc định là def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar65, nghĩa là giá trị đó sẽ không được sử dụng. Thay vì def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar66, nên viết def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar67. Khi def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar65 là một giá trị đang được sử dụng, chúng tôi sẽ giữ nguyên dạng “str, default Không có”. Ví dụ: trong def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar69, def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar65 không phải là một giá trị đang được sử dụng nhưng có nghĩa là tính năng nén là tùy chọn và không có tính năng nén nào được sử dụng nếu không được cung cấp. Trong trường hợp này, chúng tôi sẽ sử dụng def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar67. Chỉ trong các trường hợp như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar72 và def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar65 đang được sử dụng giống như cách mà def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar74 hoặc def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar75 sẽ được sử dụng, thì chúng tôi sẽ chỉ định "str, int hoặc Không, mặc định là Không" Tốt def astype(dtype): """ Cast Series type. This section will provide further details. """ pass7 Xấu def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar30 các loại thông sốKhi chỉ định các loại tham số, có thể sử dụng trực tiếp các loại dữ liệu tích hợp sẵn của Python (loại Python được ưa thích hơn chuỗi dài dòng, số nguyên, boolean, v.v.)
Đối với các loại phức tạp, xác định các loại phụ. Đối với def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar76 và def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar77, vì có nhiều hơn một loại, chúng tôi sử dụng dấu ngoặc để giúp đọc loại (dấu ngoặc nhọn cho def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar76 và dấu ngoặc vuông bình thường cho def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar77)
Trong trường hợp chỉ có một bộ giá trị được phép, hãy liệt kê chúng trong dấu ngoặc nhọn và phân tách bằng dấu phẩy (theo sau là khoảng trắng). Nếu các giá trị là thứ tự và chúng có thứ tự, hãy liệt kê chúng theo thứ tự này. Nếu không, hãy liệt kê giá trị mặc định trước, nếu có
Nếu loại được xác định trong mô-đun Python, thì mô-đun đó phải được chỉ định
Nếu loại nằm trong một gói, mô-đun cũng phải được chỉ định
Nếu loại là loại gấu trúc, hãy chỉ định gấu trúc ngoại trừ Sê-ri và Khung dữ liệu
Nếu loại chính xác không liên quan, nhưng phải tương thích với một mảng NumPy, thì có thể chỉ định giống như mảng. Nếu bất kỳ loại nào có thể lặp lại được chấp nhận, thì có thể sử dụng iterable
Nếu nhiều hơn một loại được chấp nhận, hãy phân tách chúng bằng dấu phẩy, ngoại trừ hai loại cuối cùng, cần được phân tách bằng từ 'hoặc'
Nếu def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar65 là một trong các giá trị được chấp nhận, thì giá trị đó luôn phải là giá trị cuối cùng trong danh sách Đối với trục, quy ước là sử dụng một cái gì đó như
phần 4. lợi nhuận hoặc sản lượngNếu phương thức trả về một giá trị, nó sẽ được ghi lại trong phần này. Ngoài ra nếu phương thức mang lại đầu ra của nó Tiêu đề của phần sẽ được xác định giống như "Tham số". Với tên "Returns" hoặc "Yields" được theo sau bởi một dòng có nhiều dấu gạch nối bằng các chữ cái trong từ trước đó Các tài liệu của sự trở lại cũng tương tự như các thông số. Nhưng trong trường hợp này, sẽ không có tên nào được cung cấp, trừ khi phương thức trả về hoặc mang lại nhiều hơn một giá trị (một bộ giá trị) Các loại cho "Lợi nhuận" và "Lợi nhuận" giống như các loại cho "Tham số". Ngoài ra, phần mô tả phải kết thúc bằng dấu chấm Ví dụ, với một giá trị duy nhất def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar31 Với nhiều hơn một giá trị def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar32 Nếu phương pháp mang lại giá trị của nó def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar33 Phần 5. Xem thêmPhần này được sử dụng để cho người dùng biết về chức năng gấu trúc liên quan đến chức năng đang được ghi lại. Trong một số ít trường hợp, nếu không tìm thấy phương thức hoặc chức năng liên quan nào, phần này có thể được bỏ qua Một ví dụ rõ ràng là các phương thức def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar81 và def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar82. Vì def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar82 thực hiện tương đương như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar81 nhưng ở cuối def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9 hoặc def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar86 thay vì ở đầu, bạn nên cho người dùng biết về điều đó Để đưa ra một trực giác về những gì có thể được coi là liên quan, đây là một số ví dụ
Khi quyết định những gì có liên quan, bạn chủ yếu nên sử dụng cảm giác thông thường của mình và suy nghĩ về những gì có thể hữu ích cho người dùng đọc tài liệu, đặc biệt là những người ít kinh nghiệm hơn Khi liên quan đến các thư viện khác (chủ yếu là def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar06), trước tiên hãy sử dụng tên của mô-đun (không phải bí danh như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar07). Nếu chức năng nằm trong một mô-đun không phải là mô-đun chính, chẳng hạn như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar08, hãy liệt kê toàn bộ mô-đun (e. g. def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar09) Phần này có tiêu đề, "Xem thêm" (lưu ý viết hoa S và A), theo sau là dòng có dấu gạch ngang và trước đó là dòng trống Sau tiêu đề, chúng tôi sẽ thêm một dòng cho từng phương thức hoặc chức năng có liên quan, theo sau là khoảng trắng, dấu hai chấm, một khoảng trắng khác và một mô tả ngắn minh họa chức năng của phương thức hoặc chức năng này, tại sao nó có liên quan trong ngữ cảnh này và điều gì sự khác biệt chính là giữa chức năng được ghi lại và chức năng được tham chiếu. Phần mô tả cũng phải kết thúc bằng dấu chấm Lưu ý rằng trong "Returns" và "Yields", mô tả nằm trên dòng sau loại. Tuy nhiên, trong phần này, nó nằm trên cùng một dòng, với dấu hai chấm ở giữa. Nếu mô tả không vừa trên cùng một dòng, nó có thể tiếp tục trên các dòng khác và phải được thụt vào thêm Ví dụ def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar34 Phần 6. ghi chúĐây là phần tùy chọn được sử dụng để ghi chú về việc triển khai thuật toán hoặc để ghi lại các khía cạnh kỹ thuật của hành vi chức năng Vui lòng bỏ qua nó, trừ khi bạn đã quen với việc triển khai thuật toán hoặc bạn phát hiện ra một số hành vi phản trực giác trong khi viết các ví dụ cho hàm Phần này tuân theo định dạng giống như phần tóm tắt mở rộng Phần 7. ví dụĐây là một trong những phần quan trọng nhất của chuỗi tài liệu, mặc dù được đặt ở vị trí cuối cùng, vì mọi người thường hiểu các khái niệm tốt hơn bằng ví dụ hơn là thông qua giải thích chính xác Các ví dụ trong tài liệu, bên cạnh việc minh họa cách sử dụng hàm hoặc phương thức, phải là mã Python hợp lệ, trả về đầu ra đã cho theo cách xác định và có thể được sao chép và chạy bởi người dùng Các ví dụ được trình bày dưới dạng phiên trong thiết bị đầu cuối Python. def astype(dtype): """ Cast Series type. This section will provide further details. """ pass70 được sử dụng để trình bày mã. def astype(dtype): """ Cast Series type. This section will provide further details. """ pass71 được sử dụng cho mã tiếp tục từ dòng trước. Đầu ra được trình bày ngay sau dòng mã cuối cùng tạo đầu ra (không có dòng trống ở giữa). Nhận xét mô tả các ví dụ có thể được thêm vào với các dòng trống trước và sau chúng Cách trình bày ví dụ như sau
Một ví dụ đơn giản có thể là def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar35 Các ví dụ nên ngắn gọn nhất có thể. Trong trường hợp độ phức tạp của hàm yêu cầu các ví dụ dài, nên sử dụng các khối có tiêu đề in đậm. Sử dụng sao đôi def astype(dtype): """ Cast Series type. This section will provide further details. """ pass74 để in đậm văn bản, như trong def astype(dtype): """ Cast Series type. This section will provide further details. """ pass75 Quy ước cho các ví dụMã trong các ví dụ được giả định là luôn bắt đầu bằng hai dòng không được hiển thị def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar36 Bất kỳ mô-đun nào khác được sử dụng trong các ví dụ đều phải được nhập rõ ràng, mỗi mô-đun trên một dòng (như khuyến nghị trong ) và tránh các bí danh. Tránh nhập quá nhiều, nhưng nếu cần, hãy nhập từ thư viện chuẩn trước, tiếp theo là thư viện của bên thứ ba (như matplotlib) Khi minh họa các ví dụ bằng một def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9 duy nhất, hãy sử dụng tên def astype(dtype): """ Cast Series type. This section will provide further details. """ pass77 và nếu minh họa bằng một def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar86 duy nhất, hãy sử dụng tên def astype(dtype): """ Cast Series type. This section will provide further details. """ pass79. Đối với chỉ mục, def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar300 là tên ưa thích. Nếu sử dụng một bộ đồng nhất def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9 hoặc def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar86, hãy đặt tên cho chúng là def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar303, def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar304, def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar305… hoặc def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar306, def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar307, def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar308… Nếu dữ liệu không đồng nhất và cần nhiều hơn một cấu trúc, hãy đặt tên cho chúng bằng một cái gì đó có ý nghĩa, ví dụ như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar309 và def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar310 Dữ liệu được sử dụng trong ví dụ phải càng nhỏ gọn càng tốt. Số lượng hàng được khuyến nghị là khoảng 4, nhưng hãy đặt nó thành một số có ý nghĩa đối với ví dụ cụ thể. Ví dụ: trong phương pháp def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar311, nó yêu cầu phải cao hơn 5, để hiển thị ví dụ với các giá trị mặc định. Nếu thực hiện def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar312, chúng ta có thể sử dụng một cái gì đó như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar313, vì vậy dễ dàng thấy rằng giá trị được trả về là giá trị trung bình Đối với các ví dụ phức tạp hơn (ví dụ nhóm), tránh sử dụng dữ liệu mà không có diễn giải, chẳng hạn như ma trận các số ngẫu nhiên có các cột A, B, C, D.. Thay vào đó, hãy sử dụng một ví dụ có ý nghĩa, giúp dễ hiểu khái niệm hơn. Trừ khi được yêu cầu bởi ví dụ, sử dụng tên của động vật, để giữ cho các ví dụ nhất quán. Và tính chất số của chúng Khi gọi phương thức, đối số từ khóa def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar314 được ưu tiên hơn đối số vị trí def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar315 Tốt def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar37 Xấu def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar38 Mẹo để lấy ví dụ của bạn để vượt qua các tài liệuViệc lấy các ví dụ để vượt qua các tài liệu trong tập lệnh xác thực đôi khi có thể khó khăn. Dưới đây là một số điểm chú ý
Lô trong ví dụCó một số phương pháp trong gấu trúc trả về lô. Để hiển thị các ô được tạo bởi các ví dụ trong tài liệu, tồn tại chỉ thị def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar320 Để sử dụng, hãy đặt mã tiếp theo sau tiêu đề "Ví dụ" như hình bên dưới. Cốt truyện sẽ được tạo tự động khi xây dựng tài liệu def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar4 Chia sẻ tài liệugấu trúc có một hệ thống chia sẻ tài liệu, với các biến thể nhỏ, giữa các lớp. Điều này giúp chúng tôi giữ cho các chuỗi tài liệu nhất quán, đồng thời giữ mọi thứ rõ ràng cho người dùng đọc. Nó phải trả giá bằng một số phức tạp khi viết Mỗi chuỗi tài liệu được chia sẻ sẽ có một mẫu cơ sở với các biến, chẳng hạn như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar321. Các biến được điền sau này bằng cách sử dụng trình trang trí def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar322. Cuối cùng, các chuỗi tài liệu cũng có thể được thêm vào với trình trang trí def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar322 Trong ví dụ này, chúng tôi sẽ tạo một chuỗi tài liệu gốc bình thường (điều này giống như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar324. Sau đó, chúng tôi sẽ có hai đứa con (như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar325 và def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar326). Chúng tôi sẽ thay thế tên lớp trong chuỗi tài liệu này def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar5 Các docstrings kết quả là def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar6 Lưu ý
Các tệp của chúng tôi thường sẽ chứa một def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar327 cấp mô-đun với một số giá trị thay thế phổ biến (những thứ như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar328, def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar329, v.v.) Bạn có thể thay thế và thêm vào một lần bằng thứ gì đó như def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar7 trong đó def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar330 có thể đến từ tên chức năng ánh xạ từ điển def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar331 cấp mô-đun thành chuỗi tài liệu. Bất cứ khi nào có thể, chúng tôi thích sử dụng def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar322 hơn, vì quy trình viết chuỗi tài liệu gần với bình thường hơn một chút |
