如何在Ubuntu上配置Python文档

在 Ubuntu 上配置 Python 文档

一 安装本地 Python 文档

• 安装系统自带的 Python 文档包（适用于桌面环境）：
  • 命令：sudo apt update && sudo apt install python3-doc
  • 安装完成后，文档通常位于：/usr/share/doc/python3.x/html/（可通过文件管理器或浏览器打开其中的 index.html）。
• 安装离线 HTML 文档阅读器 Devhelp（可选，便于集中查看多语言/多库文档）：
  • 命令：sudo apt install devhelp
  • 安装后可在应用菜单搜索并启动 Devhelp，在 Devhelp 中搜索并订阅 Python 手册，即可离线浏览 API 与教程。

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

• 创建并激活虚拟环境（示例）：
  • 命令：python3 -m venv venv && source venv/bin/activate
• 升级 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 生成 HTML 文档，或 pdoc --http : 启动本地文档服务

三 在 IDE 中启用文档提示

• VS Code
  • 安装扩展：Python（Microsoft 出品）
  • 在设置中启用“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 仓库；某些精简系统可能默认未启用 universe。
• 浏览器打开 file:///usr/share/doc/python3.x/html/index.html 显示为空或样式缺失：安装本地帮助查看器（如 devhelp）或改用 pydoc -b 浏览模块列表与文档。
• 虚拟环境中 pydoc 看不到全局包：这是预期行为；如需查看系统包，可在激活虚拟环境后临时使用系统解释器运行 pydoc，例如：/usr/bin/python3 -m pydoc -b。