在 Ubuntu 上配置 Python 文档

想在 Ubuntu 系统里高效地查阅 Python 文档，摆脱对网络搜索的依赖？其实，无论是查看语言本身的说明，还是研究虚拟环境中第三方库的用法，都有现成且好用的本地化方案。下面就来梳理一下几种主流的方法。

一 安装本地 Python 文档

最直接的方式，就是安装系统自带的 Python 文档包。这个方法尤其适合桌面环境用户。

• 安装系统自带的 Python 文档包：
  • 只需在终端执行一条命令：sudo apt update && sudo apt install python3-doc。
  • 安装完成后，完整的 HTML 文档通常就躺在 /usr/share/doc/python3.x/html/ 目录下。直接用文件管理器打开其中的 index.html，或者用浏览器访问这个本地文件路径，就能开始查阅了。
• 安装离线 HTML 文档阅读器 Devhelp（可选）：
  • 如果你经常需要交叉查阅不同语言或库的文档，那么一个集中的阅读器会方便很多。可以试试 Devhelp，安装命令是：sudo apt install devhelp。
  • 安装后，从应用菜单启动 Devhelp，在里面搜索并订阅 Python 手册。这样一来，所有 API 和教程的离线浏览就都搞定了。

二 在虚拟环境中查看包文档

开发时我们常使用虚拟环境来隔离项目依赖。那么，如何查看这些环境中安装的特定包的文档呢？方法有好几种。

• 创建并激活虚拟环境：
  • 这是一个标准步骤，例如：python3 -m venv venv && source venv/bin/activate。
• 升级 pip 并安装常用库：
  • 激活环境后，建议先升级 pip：python -m pip install --upgrade pip。
  • 然后安装你需要的库，比如：pip install requests numpy。
• 查看已安装包的文档：
  • 使用 help()： 在 Python 交互式环境（REPL）中，直接输入 help(requests) 或 help(numpy.array)，文档就会直接打印出来。
  • 使用 pydoc： 在终端执行 pydoc -b，它会自动在浏览器中打开一个本地服务器页面，并清晰地列出当前虚拟环境下所有可导入的模块，点击即可查看。
  • 使用 pdoc： 这是一个更现代的文档生成工具。先安装：pip install pdoc3。然后，运行 pdoc numpy 可以为 numpy 生成静态 HTML 文档；或者运行 pdoc --http : 来启动一个实时文档服务。

三 在 IDE 中启用文档提示

对于开发者而言，在集成开发环境（IDE）里直接获得文档提示，无疑是效率最高的方式。这里以两款主流的 IDE 为例。

• VS Code
  • 首先，确保安装了由 Microsoft 官方出品的 “Python” 扩展。
  • 接着，在设置中启用 “Editor › Inlay Hints › Parameter Names” 以及将 “Python › Analysis: Type Checking Mode” 设置为基本模式，这能提升提示的准确性。
  • 使用时，只需在代码中将光标悬停在函数或类名上，就能看到文档。按下 Ctrl+K Ctrl+I（Windows/Linux）可以强制查看悬停文档。利用 “Go to Definition” 或 “Peek Definition” 功能，还能直接跳转到源码查看其 docstring。
• PyCharm
  • 打开项目后，第一件事是确认已配置正确的 Python 解释器（路径：File → Settings → Project → Python Interpreter）。
  • 将光标放在某个符号上，按 Ctrl+Q 可以调出快速文档窗口；按 Ctrl+Shift+I 则能在一个小窗口内查看定义和文档，无需跳转。
  • 如果喜欢更自动化的方式，可以在设置中启用 “Show quick documentation on mouse move”，这样鼠标稍作停留，文档就会自动出现。

四 常见问题与排查

配置过程中可能会遇到一些小麻烦，别担心，通常都有明确的解决办法。

• 运行安装命令提示找不到 python3-doc 包： 先执行 sudo apt update 刷新软件源列表。如果问题依旧，请确认你的 sources.list 文件包含了 universe 仓库。一些精简版的系统可能默认没有启用它。
• 浏览器打开本地文档路径显示为空或样式丢失： 这可能是浏览器安全策略导致的。更稳妥的方法是安装前面提到的 Devhelp 这类本地帮助查看器。或者，直接使用 pydoc -b 命令，通过本地 HTTP 服务来浏览模块列表和文档，能完美避免文件协议带来的问题。
• 在虚拟环境中用 pydoc 看不到全局安装的包： 这是正常现象，因为 pydoc 默认只查看当前环境。如果确实需要查阅系统级的包文档，可以在激活虚拟环境后，显式地使用系统解释器来运行 pydoc，例如：/usr/bin/python3 -m pydoc -b。