In đậm chuỗi tài liệu python

Điều này chỉ bao gồm một vài trong số rất nhiều lệnh có sẵn thông qua nhân sư. Để biết thêm, hãy truy cập http. // nhân sư. pocoo. tổ chức/

Ngoài ra, một trang web tuyệt vời khác chỉ có tổng quan về các lệnh phổ biến hơn là http. // tài liệu. máy chủ địa lý. org/trunk/en/docguide/sphinx. html

Cài đặt nhân sư

Cố gắng

easy_install -U sphinx

Khởi động nhanh Sphinx

Để bắt đầu, hãy cd vào thư mục tài liệu và nhập.

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

Đây là danh sách mặc định được sử dụng trong dự án này

PromptChoice> Root path for the documentation [.]:> Separate source and build directories [y/N] [n]:y> Name prefix for templates and static dir [_]:> Project name:an_example_pypi_project> Author name[s]:Andrew Carter> Project version:0.0.1> Project release [0.0.1]:> Source file suffix [.rst]:> Name of your master document [without suffix] [index]:> autodoc: automatically insert docstrings from modules [y/N] [n]:y> doctest: automatically test code snippets in doctest blocks [y/N] [n]:n> intersphinx: link between Sphinx documentation of different projects [y/N] [n]:y> todo: write “todo” entries that can be shown or hidden on build [y/N] [n]:n> coverage: checks for documentation coverage [y/N] [n]:n> pngmath: include math, rendered as PNG images [y/N] [n]:n> jsmath: include math, rendered in the browser by JSMath [y/N] [n]:n> ifconfig: conditional inclusion of content based on config values [y/N] [n]:y> Create Makefile? [Y/n] [y]:n> Create Windows command file? [Y/n] [y]:n

Sau đó, bạn nên nhận được

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

conf. py

Trong thư mục doc/source của bạn hiện là một tệp python có tên conf. p .

Đây là tệp kiểm soát những điều cơ bản về cách sphinx chạy khi bạn chạy bản dựng. Ở đây bạn có thể làm điều này như

• Thay đổi số phiên bản/bản phát hành bằng cách đặt phiên bản và bản phát hành variables.
• Đặt tên dự án và tên tác giả
• Thiết lập logo dự án
• Đặt kiểu mặc định thành sphinx hoặc mặc định . Mặc định là những gì tài liệu python tiêu chuẩn sử dụng.

và nhiều hơn nữa. Duyệt qua tệp này sẽ giúp bạn hiểu những điều cơ bản

Văn bản được cấu trúc lại [reST] Tài nguyên

Sphinx được xây dựng bằng văn bản được cấu trúc lại và khi sử dụng sphinx, hầu hết nội dung bạn nhập là văn bản được cấu trúc lại. Dưới đây là một số tài nguyên tuyệt vời [và hầu hết các ví dụ được lấy ra từ các trang này]

• http. //docutils. nguồn. mạng/đầu tiên. html
• http. //docutils. nguồn. mạng/tài liệu/người dùng/đầu tiên/quickref. html
• http. //docutils. nguồn. net/docs/user/rst/cheatsheet. txt

In đậm/Nghiêng

In đậm và in nghiêng được thực hiện như thế này

**bold** and *italics*

hiển thị như in đậm và in nghiêng

danh sách

Bạn có thể làm

* A thing.
* Another thing.

or

1. Item 1.
2. Item 2.
3. Item 3.

or

- Some.
- Thing.
- Different.

kết xuất như

• Một vật
• Cái khác

hoặc là

1. Mục 1
2. Mục 2
3. Mục 3

hoặc là

• Một số
• Điều
• Khác nhau

tiêu đề

Việc chọn quy ước cho tiêu đề là tùy thuộc vào bạn và chỉ cần tuân theo quy ước đó – Sphinx sẽ tuân theo quy ước của bạn

Bạn có thể thực hiện bất kỳ chiến lược tiêu đề nào bạn muốn, nhưng tôi nghĩ một chiến lược tốt là

H1 -- Top of Page Header
************************
There should only be one of these per page and this will also -- when
converting to pdf -- be used for the chapters.

H2 -- Page Sections
===================

H3 -- Subsection
----------------

H4 -- Subsubsection
+++++++++++++++++++

Vì thế

A Subpoint
----------
This is my idea.

A subsubpoint
+++++++++++++
This is a smaller idea.

Được kết xuất như thế này

một điểm phụ

đây là ý tưởng của tôi

một điểm con

Đây là một ý tưởng nhỏ hơn

Những cái bàn

Các bảng cơ bản được thực hiện như thế này

COMPLEX TABLE:

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

SIMPLE TABLE:

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

Mà kết xuất như thế này

BẢNG PHỨC TẠP

Tiêu đề 1 Tiêu đề 2 Tiêu đề 3 nội dung hàng 1 cột 2 cột 3 nội dung hàng 2 Ô ​​có thể kéo dài các cột. hàng nội dung 3Cells có thể kéo dài hàng

• tế bào
• Lưu trữ
• khối

thân hàng 4

BẢNG ĐƠN GIẢN

InputsOutputABA or BFalseFalseFalseTrueFalseTrueFalseTrueTrueTrueTrueTrue

liên kết

Các url được liên kết tự động, như http. //gói. con trăn. org/an_example_pypi_project/

Đối với các liên kết khác, về cơ bản, bạn sử dụng toán tử _ .

Để thêm văn bản có siêu liên kết, tôi thích sử dụng định dạng này

________số 8_______

hiển thị dưới dạng Tài liệu cho dự án này

Để tạo một liên kết anchor nhảy đến một phần khác trong cùng một. tệp đầu tiên, hãy sử dụng cú pháp này

`Table of Contents`_

Cái nào hiển thị như thế này.

Hình ảnh

Cú pháp hình ảnh là như thế này

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

0

Cái nào hiển thị như thế này

Bằng chứng cho thấy làm giàu chủ yếu là may mắn

Bạn cũng có thể thêm một điểm neo cho một hình ảnh như thế này

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

1

Cái nào hiển thị như thế này

Bằng chứng cho thấy làm giàu chủ yếu là may mắn

Bây giờ bạn có thể tham khảo neo này như thế này

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

2

kết xuất như thế này

bức tranh này

Các tài liệu

Để tải tài liệu bạn sử dụng cú pháp

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

3

kết xuất giống như Dự án Pypi mẫu

thay người

Cú pháp thay thế là

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

4

Hoặc nếu bạn muốn thay thế văn bản bằng chữ, hãy sử dụng

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

5

Cái nào hiển thị như thế này

Biểu tượng

phải được sử dụng trên các thùng chứa dùng để xử lý chất thải y tế.

Tôi thật sự thích

Ghi chú

Sự thay thế thực sự hữu ích, đặc biệt khi được đưa vào một toàn cầu. rst và được đưa vào đầu mỗi tệp. Xem bên dưới để biết thêm.

Bao gồm

cú pháp

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

6

Sẽ 'nội tuyến' tệp đã cho. Một quy ước phổ biến tôi sử dụng là tạo một toàn cầu. tập tin đầu tiên có tên global. đầu tiên và đưa nó vào đầu mỗi trang. Rất hữu ích cho các liên kết đến hình ảnh phổ biến hoặc liên kết tệp phổ biến, v.v.

Mục lục

Sử dụng cú pháp

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

7

kết xuất như thế này

• Bắt đầu với công cụ thiết lập và thiết lập. p

ở đâu công cụ thiết lập , sphinx , v.v. tương ứng với công cụ thiết lập. đầu tiên và nhân sư. các tệp rst trong đường dẫn cục bộ.

Đánh dấu đoạn văn

Để thu hút sự chú ý đến một phần văn bản, hãy sử dụng đánh dấu cấp độ đoạn văn

Cấu trúc quan trọng bao gồm

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

8

Cách bạn sẽ sử dụng này là như sau

$ sphinx-quickstart

Please enter values for the following settings
[just press Enter to accept a default value, if
one is given in brackets].

9

Cái nào sẽ hiển thị như thế này

Đây là một tuyên bố

Cảnh báo

Không bao giờ, bao giờ, sử dụng mã này

Mới trong phiên bản 0. 0. 1

Bây giờ sử dụng mã này là được

Để có tài liệu đầy đủ của Sphinx về đánh dấu đoạn văn, hãy xem http. // nhân sư. pocoo. org/đánh dấu/para. html

Mã số

Mã Python trong sphinx rất dễ. Bởi vì chúng tôi đã bật pygments nên tất cả những gì chúng tôi cần làm là sử dụng . toán tử ở cuối dòng. Vì thế.

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

0

Kết xuất như thế này

Đây là một cái gì đó tôi muốn nói về

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

1

Ngoài ra, bạn có thể sử dụng . để hiển thị chính xác bất kỳ văn bản nào bằng cách sử dụng phông chữ có chiều rộng cố định và bằng cách chuyển công cụ văn bản được cấu trúc lại. Điều này rất hữu ích cho nghệ thuật ascii.

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

2

Ngoài ra, bạn có thể thêm mã "nội tuyến" bằng cách sử dụng toán tử phông chữ cố định

Bằng cách sử dụng hai dấu `` như thế này.

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

3

bạn lấy

Đây là nội tuyến if __name__ == '__main__ .

Cú pháp tham chiếu chéo Python

Sphinx giúp dễ dàng liên kết nhanh chóng với các định nghĩa mã khác trong đường dẫn python hoặc có thể được tìm thấy bởi intersphinx .

Những cái chính tôi sử dụng mọi lúc là

• chế độ
• chức năng
• tầng lớp

Cái nào được sử dụng như thế này

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

4

kết xuất như thế này

Tôi thực sự thích mô-đun có lớp

Đây là một liên kết

Để biết thêm, hãy truy cập http. // nhân sư. pocoo. org/đánh dấu/nội tuyến. html

Chỉ thị 'Tự động'

Từ các tài liệu nhân sư trực tiếp

nhân sư. mở rộng. autodoc – Bao gồm tài liệu từ chuỗi tài liệu

Tiện ích mở rộng này có thể nhập các mô-đun bạn đang ghi tài liệu và lấy tài liệu từ chuỗi tài liệu theo cách bán tự động

Ghi chú

Để Sphinx [thực ra là trình thông dịch Python thực thi Sphinx] tìm thấy mô-đun của bạn, nó phải có thể nhập được. Điều đó có nghĩa là mô-đun hoặc gói phải nằm trong một trong các thư mục trên – hãy điều chỉnh tệp cấu hình của bạn cho phù hợp

Để điều này hoạt động, tất nhiên các chuỗi tài liệu phải được viết bằng văn bản tái cấu trúc chính xác. Sau đó, bạn có thể sử dụng tất cả đánh dấu Sphinx thông thường trong chuỗi tài liệu và nó sẽ kết thúc chính xác trong tài liệu. Cùng với tài liệu viết tay, kỹ thuật này giúp giảm bớt khó khăn khi phải duy trì hai vị trí cho tài liệu, đồng thời tránh tài liệu API thuần túy được tạo tự động

Để biết thêm về autodoc, xem http. // nhân sư. pocoo. org/ext/autodoc. html

Các tính năng autodoc chính tôi sử dụng là

• .. mô-đun tự động.
• .. tự động phân loại. và
• .. chức năng tự động.

Chìa khóa để sử dụng các tính năng này là . các thành viên. thuộc tính. Nếu.

• Bạn hoàn toàn không bao gồm nó, chỉ có chuỗi tài liệu cho đối tượng được đưa vào
• Bạn chỉ cần sử dụng . các thành viên. không có đối số, thì tất cả các hàm, lớp và phương thức công khai có chuỗi doc sẽ được đưa vào đó.
• Nếu bạn liệt kê rõ ràng các thành viên như . các thành viên. fn0, class0, _fn1 những thành viên rõ ràng đó được mang đến.

Chúng tôi sẽ kiểm tra những điểm này trong ví dụ đầy đủ

Định nghĩa hàm

Chuỗi tài liệu chức năng xứng đáng được đề cập. Cú pháp nhân sư [lấy từ http. // nhân sư. pocoo. org/đánh dấu/desc. html] trông như thế này

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

5

kết xuất như thế này

format_exception[etype, value, tb [ , limit=None ]]

Định dạng ngoại lệ bằng truy nguyên

Thông số

• etype – loại ngoại lệ
• giá trị – giá trị ngoại lệ
• tb – đối tượng truy nguyên
• giới hạn [số nguyên hoặc Không có] – số khung hình ngăn xếp tối đa để hiển thị

loại trả lại

danh sách các chuỗi

Tuy nhiên, điều này có thể hơi khó đọc trong chính chuỗi tài liệu [một dòng suy nghĩ là đánh dấu nhân sư không nên giết chuỗi tài liệu mà người dùng có thể đọc qua __doc__ attribute]. In fact the google style guide //google-styleguide.googlecode.com/svn/trunk/pyguide.html says doc string should look like this:

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the sphinx-build command to build the docs, like so:
   sphinx-build -b builder .\source .\build
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

6

mà tôi nghĩ là sạch hơn rất nhiều khi bạn chỉ nhìn vào chuỗi tài liệu. Tuy nhiên, nó sẽ không có định dạng nhân sư đẹp mắt. Chúng ta sẽ thấy một ví dụ khác ở bên dưới