|
4 | 4 | "cell_type": "markdown", |
5 | 5 | "metadata": {}, |
6 | 6 | "source": [ |
7 | | - "# Python 文档资源 \n", |
8 | | - "## #注释 \n", |
| 7 | + "# 1. Python 文档资源 \n", |
| 8 | + "## 1.1 # 注释 \n", |
9 | 9 | "井号注释是代码编写文档的最基本方式。Python 会忽略 # 之后所有文字(只要 # 不是位于字符串常量中)。# 注释最适用于较小功能的文档。 \n", |
10 | 10 | "\n", |
11 | | - "## dir 函数 \n", |
| 11 | + "## 1.2 dir 函数 \n", |
12 | 12 | "内置的 dir 函数是抓取对象内可用所有属性列表的简单方式(例如,对象的方法以及较简单的数据项)。它能够调用任何有属性的对象。" |
13 | 13 | ] |
14 | 14 | }, |
15 | 15 | { |
16 | 16 | "cell_type": "code", |
17 | 17 | "execution_count": 1, |
18 | | - "metadata": {}, |
| 18 | + "metadata": { |
| 19 | + "scrolled": true |
| 20 | + }, |
19 | 21 | "outputs": [ |
20 | 22 | { |
21 | 23 | "data": { |
|
128 | 130 | { |
129 | 131 | "cell_type": "code", |
130 | 132 | "execution_count": 2, |
131 | | - "metadata": {}, |
| 133 | + "metadata": { |
| 134 | + "scrolled": true |
| 135 | + }, |
132 | 136 | "outputs": [ |
133 | 137 | { |
134 | 138 | "data": { |
|
248 | 252 | "cell_type": "markdown", |
249 | 253 | "metadata": {}, |
250 | 254 | "source": [ |
251 | | - "## 文档字符串:__doc__ \n", |
| 255 | + "## 1.3 文档字符串:__doc__ \n", |
252 | 256 | "Python 支持可自动附加在对象上的文档,而且在运行时还可保存查看。 \n", |
253 | 257 | "\n", |
254 | 258 | "从语法上来说,这类注释是写成字符串,放在模块文件、函数以及类语句的顶端,在任何可执行程序代码前。 \n", |
|
395 | 399 | { |
396 | 400 | "cell_type": "code", |
397 | 401 | "execution_count": 10, |
398 | | - "metadata": {}, |
| 402 | + "metadata": { |
| 403 | + "scrolled": true |
| 404 | + }, |
399 | 405 | "outputs": [ |
400 | 406 | { |
401 | 407 | "name": "stdout", |
|
513 | 519 | "cell_type": "markdown", |
514 | 520 | "metadata": {}, |
515 | 521 | "source": [ |
516 | | - "## PyDoc:help 函数 \n", |
| 522 | + "## 1.4 PyDoc:help 函数 \n", |
517 | 523 | "标准 PyDoc 工具是 Python 程序代码,知道如何提取文档字符串并且自动提取其结构化的信息,并将其格式化成各种类型的排列友好的列表。 \n", |
518 | 524 | "\n", |
519 | 525 | "启动 PyDoc 有很多种方法,包括命令行脚本选项,可以将生成的文档保存到以后查看。两种最主要的 PyDoc 接口是内置的 help 函数和 PyDoc GUI/HTML 接口。" |
|
1122 | 1128 | "cell_type": "markdown", |
1123 | 1129 | "metadata": {}, |
1124 | 1130 | "source": [ |
1125 | | - "## PyDoc:HTML 报表 \n", |
| 1131 | + "## 1.5 PyDoc:HTML 报表 \n", |
1126 | 1132 | "在许多环境中,特别是在交互提示符下,help 函数的文本显示是足够的。对于那些已经习惯了更丰富的展示的读者来说,它们可能看起来有点原始。 \n", |
1127 | 1133 | "\n", |
1128 | 1134 | "基于 HTML 的 PyDoc 以图形化方式呈现模块文档,以便在 web 浏览器中查看,甚至可以自动打开模块文档。 \n", |
1129 | 1135 | "\n", |
1130 | 1136 | "**Python 3.2 之后的版本** \n", |
1131 | | - "在Python 3.3中,PyDoc 的原始 GUI 客户端模式不再可用,取而代之的是 pydoc -b 命令行,它生成本地运行的文档服务器,以及同时作为搜索引擎客户端和页面显示的 web 浏览器。 \n", |
| 1137 | + "在 Python 3.3 中,PyDoc 的原始 GUI 客户端模式不再可用,取而代之的是 pydoc -b 命令行,它生成本地运行的文档服务器,以及同时作为搜索引擎客户端和页面显示的 web 浏览器。 \n", |
1132 | 1138 | "\n", |
1133 | 1139 | "还有其他方法可以使用 PyDoc(例如,将 HTML 页面保存到文件中,以供以后查看)。 \n", |
1134 | 1140 | "\n", |
1135 | | - "使用 -m Python命令行参数来方便地在模块导入搜索路径上定位 PyDoc 的模块文件。" |
| 1141 | + "使用 -m Python 命令行参数来方便地在模块导入搜索路径上定位 PyDoc 的模块文件。" |
1136 | 1142 | ] |
1137 | 1143 | }, |
1138 | 1144 | { |
|
1204 | 1210 | "cell_type": "markdown", |
1205 | 1211 | "metadata": {}, |
1206 | 1212 | "source": [ |
1207 | | - "## 不止文档字符串:Sphinx \n", |
| 1213 | + "## 1.6 不止文档字符串:Sphinx \n", |
1208 | 1214 | "如果你正在寻找一种以更精密的方式记录 Python 系统的方法,你可能希望查看 Sphinx( http://sphinx-doc.org )。Sphinx 由标准 Python 文档和许多其他项目使用。它使用简单的 reStructuredText 作为标记语言,并从 reStructuredText 解析和翻译工具的 Docutils 套件中继承了许多内容。 \n", |
1209 | 1215 | "\n", |
1210 | 1216 | "Sphinx 支持多种输出格式(包括 Windows HTML 帮助、可打印 PDF 版本的 LaTeX、手册和纯文本);广泛而自动的交叉引用;层次化结构,与相关项自动链接;自动索引;使用 Pygments 自动突出显示代码等等。对于小型的程序来说,docstring 和 PyDoc 可能已经足够了,但是对于大型项目来说,它们可以生成专业级的文档。 " |
|
1214 | 1220 | "cell_type": "markdown", |
1215 | 1221 | "metadata": {}, |
1216 | 1222 | "source": [ |
1217 | | - "# 常见编写代码的陷阱 \n", |
| 1223 | + "# 2. 常见编写代码的陷阱 \n", |
1218 | 1224 | "- **别忘了冒号。**\n", |
1219 | | - "- **从第一行开始。**\n", |
| 1225 | + "- **从第一列开始。**\n", |
1220 | 1226 | "- **空白行在交互模式提示符下很重要。**模块文件中复合语句内的空白行都会被忽略,但在交互模式提示符下的空白行则会结束语句。\n", |
1221 | 1227 | "- **缩进要一致。**避免在块缩进中混合制表符和空格。\n", |
1222 | 1228 | "- **不要在 Python 中写 C 代码。**\n", |
|
1226 | 1232 | "- **一定要使用括号调用函数。**\n", |
1227 | 1233 | "- **不要在导入和重载中使用扩展名或路径。**在 import 语句中省略目录路径和文件扩展名,要写 import mod,而不是 import mod.py。" |
1228 | 1234 | ] |
| 1235 | + }, |
| 1236 | + { |
| 1237 | + "cell_type": "code", |
| 1238 | + "execution_count": null, |
| 1239 | + "metadata": {}, |
| 1240 | + "outputs": [], |
| 1241 | + "source": [] |
1229 | 1242 | } |
1230 | 1243 | ], |
1231 | 1244 | "metadata": { |
|
0 commit comments