Omni Docs Sublime Text 插件

一个简单的 Sublime Text 插件，可以跳转到所选符号的文档

1. 导入模块 / API
2. 语言参考
3. 某些语言默认支持（参见支持的语言），但其他可以通过自定义设置添加。

基本使用方法是在需要帮助时按 F1，将显示可能的选项面板

变更日志

版本 1.2.0

• 设置 language_docs 可以是一个列表:

  • 版本 1.1.0

• 添加对 Sublime Text 2 的支持:

  • 添加了 Erlang 的文档模式
  • 安装

通过 Package Control

确保您已在 Sublime Text 中安装了 Package Control，然后按 ctrl+shift+P，输入“Install Package”并选择“OmniDocs”。

手动安装

您可以使用以下命令将 OmniDocs 库 克隆到 Sublime Text 的软件包目录（可通过“首选项 > 浏览软件包...

菜单访问）

git clone [email protected]:bordaigorl/sublime-omnidocs.git OmniDocs

或从此处下载 OmniDocs 的最新版本，并将内容提取到软件包目录中。

贡献

如果您成功添加了对语言的支持，并且认为这可能会对其他人有用，请在此GitHub 上 fork 仓库并提交 pull request。

使用方法

插件提供两个命令：omni_docs_panel 和 omni_docs_lookup。

omni_docs_panel 命令会根据设置在当前视图或当前打开的视图中查找导入的模块，并显示一个带有所需文档的快速面板。

omni_docs_lookup 命令会在文档中查找当前选定的内容。

设置控件根据语言逐个控制文档的访问和显示方式；大多数预设打开官方在线参考，但可以在设置中全面自定义，请参阅配置。

快捷键和命令

默认快捷键绑定 F1，按下时

• 如果有内容被选中，OmniDocs将在当前编程语言的文档中搜索选中符号；
• 如果没有内容被选中，将显示一个快速面板，显示当前导入的模块列表，您可以一键打开相应的文档。

要查看可用的命令，可以使用 ctrl+shift+P 打开命令面板，并输入“OmniDocs”。

默认支持的语言

• Python
• Markdown（仅语法参考）
• Haskell
• LaTeX
• Java
• Scala
• Erlang

可以通过设置轻松添加对其他语言的支持。

配置

OmniDocs被设计为支持任何语言，自定义文档源以及其他插件。要支持新的语言，更改文档源或在OmniDocs中调用自定义命令，您只需在设置中更改几行。

设置可以在文件 OmniDocs.sublime-settings 中自定义。设置也可以从 首选项 > 包首选项 > Omni Docs 访问。

注意：我们将任何加载外部文档组件的语言结构称为 导入，我们将此类组件称为 模块。导入的例子包括Python的 import 声明或LaTeX的 \usepackage。模块的例子包括Python的 os.path 和LaTeX的 tikz。

设置的基本结构如下

{
    <selector>: {
        "language_docs": {
            "command": <command>,
            "args": <args>
        },
        "lookup_docs": {
            "command": <command>,
            "args": <args>
        },
        "module_docs": {
            <matching-method>,
            "across_open_files": <true/false>,
            "command": <command>,
            "args": <args>           
        }
    },
    ...
}

<selector> 控制规则何时应用。例如，它可以是指 text.html；OmniDocs将寻找最具体的包含规则的selector。例如在markdown文档中，即使存在text.html条目，也会触发text.html.markdown条目。

如果特定selector的设置为空（即 <selector>: {}），则该作用域将被禁用；类似地，您可以通过将其设置为空对象来禁用特定部分。

特殊selector default将在没有任何selector匹配当前选择的作用域时触发。

<command> 可以是任何Sublime Text窗口命令，甚至可以是另一个插件提供的。例如 "command": "open_url", "args": {"url": <url>} 将在浏览器中打开 <url>。

<args> 字段可以包含构建系统变量中的任何一个，以及

针对selector的设置的三个主要部分是： language_docs、lookup_docs 和 module_docs。

语言和查找文档

language_docs 和 lookup_docs 设置指定当用户请求当前语言的参考和选中符号的帮助时，需要执行哪个命令。language_docs 的值也可以是列表，用于具有多个文档资源的语言。设置lookup_docs的args字段应包含$selection变量以显示相关信息。例如，一个通用的lookup_docs设置可能是{"command": "open_url", "args": {"url": "http://www.google.com/#q=$selection"}}。

模块文档

由于需要指定OmniDocs如何找到导入的模块，因此 module_docs 部分更为复杂。有两种方法可以指定：基于 作用域 和基于 模式。

基于作用域的方法

第一种也是 simplestmethods 方法使用选择器来查找模块名称。例如，在 java（使用标准 ST3 Java 语法定义）中，导入模块名称在 import 语句中标记为作用域 meta.import storage.modifier.import

"source.java": {
    "module_docs": {
        "selector": "meta.import storage.modifier.import",
        "across_open_files": true,
        "command": "open_url",
        "args": {"url": "http://javadocs.org/$module"}
    }
}

如果你更喜欢检测代码中使用的类名称作为文档的可能主题，可以使用

"selector": "storage.type - storage.type.primitive"

基于模式的方法

而不是使用 selector 设置，可以通过设置 patterns 数组来指定如何使用正则表达式（regex）提取导入。

"module_docs": {
    "patterns": [
        {
            "import_regex":   <regex>
            "import_capture": <capture> // optional
            "module_regex":   <regex>   // optional
        },
        ...
    ]
}

基于模式的方法分为两个阶段。首先，使用 import_regex 正则表达式提取包含导入的行。使用 import_capture，您可以使用 import_regex 的捕获组来从中提取导入的模块名称（s）；如果未指定，则使用完整匹配。其次，如果指定了 module_regex，则从匹配项中提取模块名称。此步骤是可选的，但在解析包含多个模块的导入时是必需的。

例如，要解析 python 中的 import string, os.path，您需要将导入与 "import_regex": "^\\s*import\\s+([a-zA-Z0-9.\\-\\_, ]+)$" 匹配，捕获模块列表 "import_capture": "$1"，最后指定 "module_regex": "[a-zA-Z0-9.\\-\\_]+"，以便可以匹配提取列表中的模块名称。

配置示例

"text.tex": {
    "module_docs": {
        "patterns": [{
            "import_regex": "\\\\usepackage(\\[\\w*\\])?\\{([^\\}]*)\\}",
            "import_capture": "$2",
            "module_regex": "[^ \n\t,]+"
        }],
        "across_open_files": true,
        "command": "exec",
        "args": {"cmd": ["texdoc", "${module}"]}
    },
    "language_docs":{
        "command": "open_url",
        "args": {"url": "http://svn.gna.org/viewcvs/*checkout*/latexrefman/trunk/latex2e.html"}
    },
    "lookup_docs": {
        "command": "open_url",
        "args": {"url": "http://tex.stackexchange.com/search?q=${selection}"}
    }
}

待办事项

• 内置对更多语言的支持
• 添加一个命令来请求解析并显示文档的 JSON
• 考虑切换到由语法特定设置文件驱动的设置