Chữ nghiêng python

Wrapping là hiện một phần nội dung của văn bản được đưa xuống các dòng bên dưới nếu độ dài của văn bản lớn hơn chiều rộng của phần tử cha

văn bản-gói-ví dụ


Text Wrapping

Bootstrap is a free and open-source front-end framework.

Chữ nghiêng python

Application Layer. text-nowrap for phần tử cha để loại bỏ hiện tượng gói, nhưng bạn sẽ thấy hiện tượng văn bản bị tràn (tràn) ra bên ngoài phần tử cha

văn bản-nowrap-ví dụ


.text-nowrap

Bootstrap is a free and open-source front-end framework.

Để tránh nội dung văn bản tràn ra bên ngoài phần tử cha bạn có thể sử dụng lớp. text-truncate để áp dụng cho phần tử cha, phần nội dung tràn ra bên ngoài sẽ bị ẩn đi và xuất hiện 3 dấu chấm (. ) ở cuối văn bản

Lớp .text-truncate chỉ áp dụng được cho các phần tử được thiết lập {display:block} hoặc {display:inline-block}. Chú ý:

,

mặc định được thiết lập {display:block}.

văn bản-cắt ngắn-ví dụ


.text-truncate

Bootstrap is a free and open-source front-end framework.

3- Chuyển đổi văn bản (Chuyển đổi văn bản)

Bootstrap cung cấp một vài lớp để chuyển đổi (transform) văn bản

ClassMô tả. text-lowercaseChuyển đổi (biến đổi) text thành chữ thường (chữ thường). text-uppercaseChuyển đổi văn bản thành chữ hoa (chữ hoa). text-capitalizeTất cả các ký tự đầu tiên trong mỗi chữ sẽ thành ký tự hoa, còn các ký tự khác không thay đổi

văn bản-chuyển đổi-ví dụ


Origin Text:

bootSTrap teXt


.text-lowercase

bootSTrap teXt

.text-uppercase

bootSTrap teXt

.text-capitalize

bootSTrap teXt

4- Font đậm & nghiêng

Để thiết lập trọng lượng (trọng lượng) và kiểu dáng nghiêng (kiểu nghiêng) cho văn bản trong CSS, bạn sử dụng các cách dưới đây


font-weight: normal;
font-weight: bold;
font-weight: bolder;
font-weight: lighter;

font-style: normal;
font-style: italic;
font-style:oblique;
 

Thay vì sử dụng các thuộc tính Css nói trên, bạn có thể sử dụng các lớp được xây dựng sẵn của Bootstrap

  • font-trọng-đậm
  • font-weight-bình thường
  • font-weight-light
  • chữ nghiêng

font-weight-italic-ví dụ


Font weight, italic

(.font-weight-bold) Bold text.

(.font-weight-normal) Normal weight text.

(.font-weight-light) Light weight text.

(.font-italic) Italic text.

5- Phông chữ đơn cách

Phông chữ đơn cách. Là phông chữ mà mỗi ký tự (ký tự) đều có chiều dài theo phương nằm ngang như nhau. Nó giống với hình minh họa dưới đây

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

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

  • hướng dẫn chuỗi tài liệu numpydoc (dựa trên tài liệu Hướng dẫn ban đầu về tài liệu NumPy/SciPy)

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

  • Sphinx reStructuredText primer

  • Tái cấu trúc nhanhTham khảo văn bản

  • Thông số kỹ thuật tái cấu trúc đầy đủ

pandas có một số trình trợ giúp để chia sẻ chuỗi tài liệu giữa các lớp liên quan, xem Chia sẻ chuỗi tài liệu .

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ệu #

Quy định chung#

Cá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 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

  • Tên của một tham số

  • Mã Python, một mô-đun, chức năng, tích hợp sẵn, loại, chữ… (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 + bar
    
    8,
    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
    
    9,
    def astype(dtype):
        """
        Cast Series type.
    
        This section will provide further details.
        """
        pass
    
    0,
    def astype(dtype):
        """
        Cast Series type.
    
        This section will provide further details.
        """
        pass
    
    1,
    def astype(dtype):
        """
        Cast Series type.
    
        This section will provide further details.
        """
        pass
    
    2)

  • Một lớp gấu trúc (ở dạng

    def astype(dtype):
        """
        Cast Series type.
    
        This section will provide further details.
        """
        pass
    
    3)

  • Phương thức pandas (ở dạng

    def astype(dtype):
        """
        Cast Series type.
    
        This section will provide further details.
        """
        pass
    
    4)

  • Hàm gấu trúc (ở dạng

    def astype(dtype):
        """
        Cast Series type.
    
        This section will provide further details.
        """
        pass
    
    5)

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ó là ____. Ví dụ:

def astype(dtype):
    """
    Cast Series type.

    This section will provide further details.
    """
    pass
7 sẽ liên kết đến
def astype(dtype):
    """
    Cast Series type.

    This section will provide further details.
    """
    pass
8 nhưng chỉ hiển thị phần cuối cùng,
def astype(dtype):
    """
    Cast Series type.

    This section will provide further details.
    """
    pass
9 dưới dạng văn bản liên kết. Xem cú pháp tham chiếu chéo Sphinx để biết chi tiết

Tốt


.text-nowrap

Bootstrap is a free and open-source front-end framework.
9

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ắn#

Tó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


.text-truncate

Bootstrap is a free and open-source front-end framework.
2


.text-truncate

Bootstrap is a free and open-source front-end framework.
3


.text-truncate

Bootstrap is a free and open-source front-end framework.
4


.text-truncate

Bootstrap is a free and open-source front-end framework.
5

Phần 2. tóm tắt mở rộng#

Tó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


.text-truncate

Bootstrap is a free and open-source front-end framework.
6

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 đề “Thông số”, theo sau là một dòng có dấu gạch nối dưới mỗi chữ cái của từ “Thông 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


.text-truncate

Bootstrap is a free and open-source front-end framework.
20 và

.text-truncate

Bootstrap is a free and open-source front-end framework.
21, nhưng không phải

.text-truncate

Bootstrap is a free and open-source front-end framework.
22

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


.text-truncate

Bootstrap is a free and open-source front-end framework.
20 và

.text-truncate

Bootstrap is a free and open-source front-end framework.
21, 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 đối số mặc định nghĩa là gì, 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à


.text-truncate

Bootstrap is a free and open-source front-end framework.
25, nghĩa là giá trị đó sẽ không được sử dụng. Thay vì

.text-truncate

Bootstrap is a free and open-source front-end framework.
26, nên viết

.text-truncate

Bootstrap is a free and open-source front-end framework.
27. Khi

.text-truncate

Bootstrap is a free and open-source front-end framework.
25 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

.text-truncate

Bootstrap is a free and open-source front-end framework.
29,

.text-truncate

Bootstrap is a free and open-source front-end framework.
25 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

.text-truncate

Bootstrap is a free and open-source front-end framework.
27. Chỉ trong các trường hợp như

.text-truncate

Bootstrap is a free and open-source front-end framework.
32 và

.text-truncate

Bootstrap is a free and open-source front-end framework.
25 đang được sử dụng giống như cách mà

.text-truncate

Bootstrap is a free and open-source front-end framework.
34 hoặc

.text-truncate

Bootstrap is a free and open-source front-end framework.
35 sẽ được sử dụng, khi đó chúng tôi sẽ chỉ định “str, int hoặc Không có, mặc định là Không có”

Tốt


font-weight: normal;
font-weight: bold;
font-weight: bolder;
font-weight: lighter;

font-style: normal;
font-style: italic;
font-style:oblique;
 
3

Xấu


.text-nowrap

Bootstrap is a free and open-source front-end framework.
90

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.)

  • int

  • trôi nổi

  • str

  • bool

Đối với các loại phức tạp, xác định các loại phụ. Đối với


.text-truncate

Bootstrap is a free and open-source front-end framework.
36 và

.text-truncate

Bootstrap is a free and open-source front-end framework.
37, vì có nhiều 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

.text-truncate

Bootstrap is a free and open-source front-end framework.
36 và dấu ngoặc vuông bình thường cho

.text-truncate

Bootstrap is a free and open-source front-end framework.
37)

  • danh sách int

  • lệnh của {str. int}

  • bộ của (str, int, int)

  • bộ của (str,)

  • bộ str

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ó

  • {0, 10, 25}

  • {'đơn giản', 'nâng cao'}

  • {'thấp trung bình cao'}

  • {'mèo', 'chó', 'chim'}

Nếu loại được xác định trong mô-đun Python, thì mô-đun đó phải được chỉ định

  • ngày giờ. ngày

  • ngày giờ. ngày giờ

  • số thập phân. Số thập phân

Nếu loại nằm trong một gói, mô-đun cũng phải được chỉ định

  • cục mịch. ndarray

  • scipy. thưa thớt. coo_matrix

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

  • dạng mảng

  • lặp đi lặp lại

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'

  • int hoặc float

  • phao, số thập phân. Số thập phân hoặc Không có

  • str hoặc danh sách str

Nếu


.text-truncate

Bootstrap is a free and open-source front-end framework.
25 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ư

  • trục. {0 hoặc 'chỉ mục', 1 hoặc 'cột', Không có}, mặc định Không có

phần 4. lợi nhuận hoặc sản lượng #

Nế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 theo cách tương tự như “Thông số”. Với các tên “Returns” hoặc “Yields” theo sau là 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


.text-nowrap

Bootstrap is a free and open-source front-end framework.
91

Với nhiều hơn một giá trị


.text-nowrap

Bootstrap is a free and open-source front-end framework.
92

Nếu phương pháp mang lại giá trị của nó


.text-nowrap

Bootstrap is a free and open-source front-end framework.
93

Phần 5. Xem thêm#

Phầ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 sẽ là các phương thức


.text-truncate

Bootstrap is a free and open-source front-end framework.
41 và

.text-truncate

Bootstrap is a free and open-source front-end framework.
42. Vì

.text-truncate

Bootstrap is a free and open-source front-end framework.
42 thực hiện tương đương như

.text-truncate

Bootstrap is a free and open-source front-end framework.
41 nhưng ở cuối
def astype(dtype):
    """
    Cast Series type.

    This section will provide further details.
    """
    pass
9 hoặc

.text-truncate

Bootstrap is a free and open-source front-end framework.
46 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ụ

  • 
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    47 và
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    48, vì chúng làm tương tự, nhưng trong một trường hợp cung cấp các chỉ số và ở các vị trí khác

  • 
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    49 và
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    50, khi chúng làm ngược lại

  • 
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    51,
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    52 và
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    53, vì người dùng dễ dàng tìm kiếm phương thức lặp qua các cột lại kết thúc bằng phương thức lặp qua hàng và ngược lại

  • 
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    54 và
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    55, vì cả hai phương pháp đều được sử dụng để xử lý các giá trị bị thiếu

  • 
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    56 và
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    57, vì chúng bổ sung cho nhau

  • 
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    58 và
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    59, vì cái này là tổng quát của cái kia

  • 
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    60 và
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    61, vì người dùng có thể đang đọc tài liệu về
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    60 để biết cách truyền ngày tháng và cách thực hiện là với
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    61

  • 
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    64 có liên quan đến
    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    65, vì chức năng của nó dựa trên nó

Khi quyết định những gì có liên quan, bạn chủ yếu nên sử dụng ý thức chung 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à


.text-truncate

Bootstrap is a free and open-source front-end framework.
66), trước tiên hãy sử dụng tên của mô-đun (không phải bí danh như

.text-truncate

Bootstrap is a free and open-source front-end framework.
67). 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ư

.text-truncate

Bootstrap is a free and open-source front-end framework.
68, hãy liệt kê mô-đun đầy đủ (e. g.

.text-truncate

Bootstrap is a free and open-source front-end framework.
69)

Phần này có tiêu đề, “Xem thêm” (lưu ý chữ S và A viết hoa), theo sau là dòng có dấu gạch ngang và phía 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à dấu cách, dấu hai chấm, dấu cách 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ì . 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ụ


.text-nowrap

Bootstrap is a free and open-source front-end framework.
94

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à người dùng có thể sao chép và chạy

Các ví dụ được trình bày dưới dạng phiên trong thiết bị đầu cuối Python.


font-weight: normal;
font-weight: bold;
font-weight: bolder;
font-weight: lighter;

font-style: normal;
font-style: italic;
font-style:oblique;
 
30 được sử dụng để trình bày mã.

font-weight: normal;
font-weight: bold;
font-weight: bolder;
font-weight: lighter;

font-style: normal;
font-style: italic;
font-style:oblique;
 
31 đượ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

  1. Nhập các thư viện cần thiết (ngoại trừ

    
    

    .text-truncate

    Bootstrap is a free and open-source front-end framework.
    66 và
    
    font-weight: normal;
    font-weight: bold;
    font-weight: bolder;
    font-weight: lighter;
    
    font-style: normal;
    font-style: italic;
    font-style:oblique;
     
    
    33)

  2. Tạo dữ liệu cần thiết cho ví dụ

  3. Hiển thị một ví dụ rất cơ bản đưa ra ý tưởng về trường hợp sử dụng phổ biến nhất

  4. Thêm các ví dụ có giải thích minh họa cách sử dụng các tham số cho chức năng mở rộng

Một ví dụ đơn giản có thể là


.text-nowrap

Bootstrap is a free and open-source front-end framework.
95

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


font-weight: normal;
font-weight: bold;
font-weight: bolder;
font-weight: lighter;

font-style: normal;
font-style: italic;
font-style:oblique;
 
34 để in đậm văn bản, như trong

font-weight: normal;
font-weight: bold;
font-weight: bolder;
font-weight: lighter;

font-style: normal;
font-style: italic;
font-style:oblique;
 
35

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 này không được hiển thị


.text-nowrap

Bootstrap is a free and open-source front-end framework.
96

Bất kỳ mô-đun nào khác được sử dụng trong các ví dụ phải được nhập rõ ràng, mỗi mô-đun trên một dòng (như được khuyến nghị trong PEP 8#imports) 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.
    """
    pass
9 duy nhất, hãy sử dụng tên

font-weight: normal;
font-weight: bold;
font-weight: bolder;
font-weight: lighter;

font-style: normal;
font-style: italic;
font-style:oblique;
 
37 và nếu minh họa bằng một

.text-truncate

Bootstrap is a free and open-source front-end framework.
46 duy nhất, hãy sử dụng tên

font-weight: normal;
font-weight: bold;
font-weight: bolder;
font-weight: lighter;

font-style: normal;
font-style: italic;
font-style:oblique;
 
39. Đối với các chỉ số,

.text-nowrap

Bootstrap is a free and open-source front-end framework.
900 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.
    """
    pass
9 hoặc

.text-truncate

Bootstrap is a free and open-source front-end framework.
46, hãy đặt tên cho chúng là

.text-nowrap

Bootstrap is a free and open-source front-end framework.
903,

.text-nowrap

Bootstrap is a free and open-source front-end framework.
904,

.text-nowrap

Bootstrap is a free and open-source front-end framework.
905… hoặc

.text-nowrap

Bootstrap is a free and open-source front-end framework.
906,

.text-nowrap

Bootstrap is a free and open-source front-end framework.
907,

.text-nowrap

Bootstrap is a free and open-source front-end framework.
908… 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ư

.text-nowrap

Bootstrap is a free and open-source front-end framework.
909

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


.text-nowrap

Bootstrap is a free and open-source front-end framework.
911, 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

.text-nowrap

Bootstrap is a free and open-source front-end framework.
912, chúng ta có thể sử dụng một cái gì đó như

.text-nowrap

Bootstrap is a free and open-source front-end framework.
913, 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


.text-nowrap

Bootstrap is a free and open-source front-end framework.
914 được ưu tiên hơn đối số vị trí

.text-nowrap

Bootstrap is a free and open-source front-end framework.
915

Tốt


.text-nowrap

Bootstrap is a free and open-source front-end framework.
97

Xấu


.text-nowrap

Bootstrap is a free and open-source front-end framework.
98

Mẹo để các ví dụ của bạn vượt qua bài kiểm tra#

Việ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ú ý

  • Nhập tất cả các thư viện cần thiết (ngoại trừ pandas và NumPy, những thư viện này đã được nhập dưới dạng

    
    

    .text-nowrap

    Bootstrap is a free and open-source front-end framework.
    916 và
    
    

    .text-nowrap

    Bootstrap is a free and open-source front-end framework.
    917) và xác định tất cả các biến bạn sử dụng trong ví dụ

  • Cố gắng tránh sử dụng dữ liệu ngẫu nhiên. Tuy nhiên, dữ liệu ngẫu nhiên có thể ổn trong một số trường hợp, chẳng hạn như nếu hàm bạn đang ghi lại liên quan đến phân phối xác suất hoặc nếu lượng dữ liệu cần thiết để làm cho kết quả của hàm có ý nghĩa là quá nhiều, thì việc tạo thủ công sẽ rất cồng kềnh. Trong những trường hợp đó, hãy luôn sử dụng một nguồn gốc ngẫu nhiên cố định để làm cho các ví dụ được tạo có thể dự đoán được. Thí dụ

    
    

    .text-nowrap

    Bootstrap is a free and open-source front-end framework.
    99

  • Nếu bạn có một đoạn mã bao gồm nhiều dòng, bạn cần sử dụng '…' trên các dòng tiếp theo

    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
    
    0

  • Nếu bạn muốn hiển thị một trường hợp ngoại lệ được nêu ra, bạn có thể là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 + bar
    
    1

    Điều cần thiết là bao gồm “Traceback (lần gọi gần đây nhất). ”, nhưng đối với lỗi thực tế thì chỉ tên lỗi là đủ

  • Nếu có một phần nhỏ của kết quả có thể thay đổi (e. g. một hàm băm trong biểu diễn đối tượng), bạn có thể sử dụng

    
    font-weight: normal;
    font-weight: bold;
    font-weight: bolder;
    font-weight: lighter;
    
    font-style: normal;
    font-style: italic;
    font-style:oblique;
     
    
    31 để biểu diễn phần này

    Nếu bạn muốn chỉ ra rằng

    
    

    .text-nowrap

    Bootstrap is a free and open-source front-end framework.
    919 trả về một đối tượng AxesSubplot matplotlib, điều này sẽ thất bại trong doctest

    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
    
    2

    Tuy nhiên, bạn có thể làm được (chú ý phần chú thích cần bổ sung)

    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
    
    3

Đồ thị trong các 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ị


.text-nowrap

Bootstrap is a free and open-source front-end framework.
920

Để sử dụng nó, 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 + bar
4

Chia sẻ tài liệu#

gấ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ư


.text-nowrap

Bootstrap is a free and open-source front-end framework.
921. Các biến được điền sau này bằng cách sử dụng trình trang trí

.text-nowrap

Bootstrap is a free and open-source front-end framework.
922. 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í

.text-nowrap

Bootstrap is a free and open-source front-end framework.
922

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ư


.text-nowrap

Bootstrap is a free and open-source front-end framework.
924. Sau đó, chúng tôi sẽ có hai con (như

.text-nowrap

Bootstrap is a free and open-source front-end framework.
925 và

.text-nowrap

Bootstrap is a free and open-source front-end framework.
926). 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 + bar
5

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 + bar
6

Để ý

  1. Chúng tôi "nối" chuỗi tài liệu gốc vào chuỗi tài liệu con, ban đầu trống

Các tệp của chúng tôi thường chứa một


.text-nowrap

Bootstrap is a free and open-source front-end framework.
927 cấp mô-đun với một số giá trị thay thế phổ biến (những thứ như

.text-nowrap

Bootstrap is a free and open-source front-end framework.
928,

.text-nowrap

Bootstrap is a free and open-source front-end framework.
929, v.v.)

Bạn có thể thay thế và thêm vào trong một lần chụp 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 + bar
7

trong đó


.text-nowrap

Bootstrap is a free and open-source front-end framework.
930 có thể đến từ tên chức năng ánh xạ từ điển cấp độ mô-đun

.text-nowrap

Bootstrap is a free and open-source front-end framework.
931 thành chuỗi tài liệu. Bất cứ nơi nào có thể, chúng tôi thích sử dụng

.text-nowrap

Bootstrap is a free and open-source front-end framework.
922 hơn, vì các 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