将笔记本集成到 Mathematica 的文档中心

Question

如果您已经使用 Mathematica 一段时间了，您可能已经对文档中心产生了浓厚的兴趣。您总能在这些页面中找到新的东西。让它成为一个函数的选项，或者只是一些在某些时候对您来说似乎没有用的示例。

您可能已经用您一直使用的专用函数编写了包。有时您可能会想到一个与您的函数一起使用的简洁示例，但它最终可能会被遗忘在硬盘中的某个地方。如果您在想到它时就将其写入文档，也许您以后就不会拼命寻找它了。

因此，我想知道如何以编程方式将您自己的函数的文档与 Mathematica 的文档中心集成。这个问题是为了探讨如何调整文档。如果您编写了可以帮助您执行此操作的脚本，请与社区分享。

Wolfram 的工作台不是这个问题的可接受的解决方案。一切都必须通过简单安装 Mathematica 来完成。该解决方案应涵盖以下几点：

1. 为函数创建文档（最好是模板）。
2. 创建指南和教程（如果它们认为有用）。
3. 将笔记本链接到文档中心。
4. 创建在不同环境中正确显示的“使用”消息。
   • 在 Mathematica Notebook 中 ?Symbol
   • 在文档中心搜索：符号

这是一个非常广泛的主题，我有 1、2 和 3 的解决方案。我缺少第 4 点。请告诉我们，您如何通过文档中心记录您的功能？

---

更新

我添加了另一个答案。希望这个答案能够更加鼓励 Mathematica 用户用他们的包编写文档页面。我认为编写文档页面对应用程序编写者以及应用程序的用户都有好处。如果您下载我编写的包，我建议您按照教程进行操作，以便您可以看到每一步发生的情况。这将为您未来的项目提供宝贵的经验。

Github（2014 年 5 月 24 日）

自从我编写这个包以来，已经有几个人对此包感兴趣。我已将包上传到Github： https://github.com/jmlopez-rod/ApplicationMaker 。如果您想成为存储库的贡献者，请与我联系。

Answer 1

为了展示如何创建合并到文档中心的文档，我们将创建一个包含非常简单的函数及其文档的包。让我们调用我们的包SOPackage。该包将存储在同名的文件夹中，并且该文件夹应存储在 $BaseDirectory 或 $UserBaseDirectory$ 中。 SOPakage 文件夹需要具有以下树结构。

请注意，根目录是目录 SOPackage。

SOPackage

现在我们将在 SOPackage 中创建一个新的笔记本文件：SOPackage.nb。这些是笔记本的内容

BeginPackage["SOPackage`"];
AddTwo::usage = "AddTwo[\!\(\*StyleBox[\"a\", \"TI\"]\), \!\(\*StyleBox[\"b\", \"TI\"]\)] returns \!\(\*StyleBox[\"a\", \"TI\"]\)+\!\(\*StyleBox[\"b\", \"TI\"]\).";
DotTwo::usage = "DotTwo[\!\(\*StyleBox[\"a\", \"TI\"]\), \!\(\*StyleBox[\"b\", \"TI\"]\)] returns \!\(\*StyleBox[\"a\", \"TI\"]\)*\!\(\*StyleBox[\"b\", \"TI\"]\).";
AddTwo::argnum = "AddTwo was called with `1` arguments. It expected 2.";
DotTwo::argnum = "DotTwo was called with `1` arguments. It expected 2.";
Begin["`Private`"];
AddTwo[a_, b_] := a + b
AddTwo[args___] := (Message[AddTwo::argnum, Length[{args}]]; $Failed)
DotTwo[a_, b_] := a*b
DotTwo[args___] := (Message[DotTwo::argnum, Length[{args}]]; $Failed)
End[];
EndPackage[];

这是您应该看到的屏幕截图

请注意，使用消息通常将参数格式化为一种特殊的方式。获取此格式的快捷方式（由@alexey-popkov指出）是突出显示要格式化的字母，按Command+0（在Windows中为Alt+0）并输入“TI”。对所有需要修改的字母重复此过程。通过Cell->CellProperties->Initialization Cell将单元格更改为初始化单元格。现在我们将此笔记本另存为 SOPackage.nb。如果 Mathematica 没有询问您是否要创建包，因为您忘记将单元格更改为初始化单元格，那么您可以转到Format->OptionInspector。确保您选择“Options for SOPackage.nb”，否则您需要设置为 true 的选项将显示为灰色。现在单击Notebook Options->FileOptions->AutoGeneratePackage并选择Automatic。关闭选项窗口并保存文件。每次保存 SOPackage.nb 时，文件 SOPackage.m 都会更新（不要弄乱这个 m 文件）。

Kernel 目录应仅包含一个文件：init.m。该文件需要包含下一行：

Get["SOPackage`SOPackage`"];

在这之后我们就有了一个工作包。您可以尝试以下操作来确保一切正常：

<<SOPackage`
?AddTwo
?DotTwo
DotTwo[]
DotTwo[2, 3]

文档

让我们从创建指南页面开始。当您在文档中心输入 SOPackage 时，将显示该页面。首先，我们创建一个笔记本并将其保存在 SOPackage/Documentation/English/Guides 下，命名为 SOPackage_E.nb。我给它扩展名“_E”的原因是因为这将是一个可编辑的副本。请注意，您无法编辑文档中心中的任何文档。好吧，你可以，但这些更改永远不会生效。您可能希望在构建包时修改文档，因此最好拥有一个可以编辑的副本。对于此示例，我们可以复制 Combinatorica 指南 的内容，在文档中心输入 Combinatorica/guide/CombinatoricaPackage 选择所有包含单元格的内容，将其复制并粘贴到您的 SOPackage_E.nb 文件（或者，复制文件 C:\Program Files\Wolfram Research\Mathematica\10.4\Documentation\English\Packages\Combinatorica\Documentation\English\Guides\CombinatoricaPackage.nb 或其他操作系统上的同等内容）。进行一些更改，以便您知道它们是您正在做出的更改。就我而言，我用 SOPackage 替换 Combinatorica。如果您无法修改文本的某些部分，您需要执行以下操作：

1：单击无法修改的文本。

2：转到 Cell->Show Expression 或输入 Command+Shift+E 或 Windows 中的等效键。

3：在 Cell 表达式中查找第二个参数（就在任何A -> B 形式的选项）。这是一个样式名称。在某些情况下，您会看到“用法”、“注释”、“对象名称”等。找到无法修改的单元格样式后，单击正在编辑的笔记本，然后输入 Command+Shift+E 以显示表达式。

4：转到格式->编辑样式表...，在输入样式名称：下输入您之前看到的样式名称。

5：出现显示样式的单元格。确保选择此单元格并转到Format->Object Inspector。确保显示显示选项值 选择。

6：转到编辑选项并将Editable设置为true。

7：修改不可修改的。

我建议您首先输入您希望能够编辑的所有样式的名称，就像我一样如屏幕截图所示。到目前为止，我只更改了我在步骤 3 中提到的那些。将它们放入列表后，将它们全部选中并立即将其设置为可编辑。另一个重要的一点是这个文件可以是一个模板。您应该将此文件保存在某个地方，当您需要制作文档时，只需将其打开，用另一个名称将其保存在正确的路径中，然后开始从现有文档笔记本复制单元格。

如何创建本指南取决于您。现在先来说说废话吧。你会看到我的截图。接下来的两个文件是您的函数的文档。将模板文件复制并粘贴到 SOPackage/Documentation/English/ReferencePages/Symbols 并将文件命名为 AddTwo_E.nb 和 DotTwo_E.nb。查找一些您喜欢的文档，以 Sin 为例，然后将信息复制并粘贴到这些文件中。我将更改名称只是为了展示它们是如何工作的。

^{肯定可以减少模板文件的创建。如果有人知道如何以编程方式执行此操作，请随时在此处编辑此部分并将其替换为代码。您将为我们大家带来很大的帮助。}

PacletInfo.m

该文件位于 SOPackage 目录下，包含以下内容：

Paclet[
Name -> "SOPackage",
Version -> "0.0.1",
MathematicaVersion -> "8+",
Extensions -> {{
    "Documentation", 
    Resources -> {
        "Guides/SOPackage"
    }, 
    Language -> "English"
}}
]

在获得文档准备好了。我们需要使所有函数文档不可编辑，并且必须为其提供与其余文档相同的格式。这次我编写了一个脚本来执行此操作。我将其称为 MakeDoc，因为它还将构建索引。将此文件保存在 OSPackage 下。我将把这个文件分成两部分，以便您能够得到解释。

pname = "SOPackage";
Get[pname <> "`"];
basepath = $UserBaseDirectory<>"/Applications/"<>pname<>"/Documentation/English/ReferencePages/Symbols/";
$UserBaseDirectory <> "/Applications/" <> pname <> "/Documentation/English/ReferencePages/Symbols/";

我们应该确保在执行此操作之前重新启动 Mathematica。首先，我们将加载包并设置所有函数文档的根目录。在下一步中，我们基本上将复制粘贴代码，我们将为每个函数执行以下操作。

snname := "AddTwo";
nb = NotebookOpen[basepath <> snname <> "_E.nb"];
NotebookSave[nb, basepath <> snname <> ".nb"];
SetOptions[nb,
  TaggingRules -> {
    "ModificationHighlight" -> False,
    "Metadata" -> {
      "context" -> pname <> "`",
      "keywords" -> {},
      "index" -> True,
      "label" -> "OSPackage Package Paclet Symbol",
      "language" -> "en",
      "paclet" -> "OSPackage Package",
      "status" -> "",
      "summary" -> AddTwo::usage,
      "synonyms" -> {},
      "title" -> "AddTwo",
      "type" -> "Symbol",
      "uri" -> pname <> "/ref/AddTwo"},
    "SearchTextTranslated" -> ""
    }
  ];
SetOptions[nb, Saveable -> False];
SetOptions[nb, 
  StyleDefinitions -> 
   FrontEnd`FileName[{"Wolfram"}, "Reference.nb"]];
NotebookSave[nb];

此代码块打开可编辑的函数文档。它以正确的名称保存它。然后它更改其属性，使其不可编辑，并使其具有与其他文档相同的外观。我们对每个函数都做同样的事情。请注意，“summary”被设置为函数的 usage 消息。这就是我们搜索该函数时会看到的内容。

snname := "DotTwo";
nb = NotebookOpen[basepath <> snname <> "_E.nb"];
NotebookSave[nb, basepath <> snname <> ".nb"];
SetOptions[nb,
  TaggingRules -> {
    "ModificationHighlight" -> False,
    "Metadata" -> {
      "context" -> pname <> "`",
      "keywords" -> {},
      "index" -> True,
      "label" -> "OSPackage Package Paclet Symbol",
      "language" -> "en",
      "paclet" -> "OSPackage Package",
      "status" -> "",
      "summary" -> DotTwo::usage,
      "synonyms" -> {},
      "title" -> "DotTwo",
      "type" -> "Symbol",
      "uri" -> pname <> "/ref/DotTwo"},
    "SearchTextTranslated" -> ""
    }
  ];
SetOptions[nb, Saveable -> False];
SetOptions[nb, 
  StyleDefinitions -> 
   FrontEnd`FileName[{"Wolfram"}, "Reference.nb"]];
NotebookSave[nb];

非常重要的是，我们没有修改指南，这就是所需的一切：

snname := "SOPackage";
nb = NotebookOpen[guidepath <> snname <> "_E.nb"];
NotebookSave[nb, guidepath <> snname <> ".nb"];
SetOptions[nb, Saveable -> False];
SetOptions[nb, StyleDefinitions -> FrontEnd`FileName[{"Wolfram"}, "Reference.nb"]];
NotebookSave[nb];

最后，我们像这样创建索引：

indir = $UserBaseDirectory<>"/Applications/"<>pname<>"/Documentation/English/Index";
If[FileNames[indir] != {}, DeleteDirectory[indir, DeleteContents -> True]];
ind = DocumentationSearch`NewDocumentationNotebookIndexer[indir];
DocumentationSearch`AddDocumentationNotebook[ind, basepath <> "AddTwo.nb"];
DocumentationSearch`AddDocumentationNotebook[ind, basepath <> "DotTwo.nb"];
DocumentationSearch`CloseDocumentationNotebookIndexer[ind];

请注意，我们需要为每个函数添加一行 AddDocumenationNotebook 。运行 MakeDoc.nb 后，将创建文件 AddTwo.nb、DotTwo.nb 和 SOPackage.nb。这些文件无法修改。您还将看到一个名为 Index 的文件夹。这是包含文档中心信息的所有二进制数据。如果您对文档进行了修改，您应该运行 MakeDoc.nb 以使更改生效。这是我们现在拥有的文档树。

之后我们应该重新启动 Mathematica 并查看我们的文档。

这就是当您查找“SOPackage”时会发生的情况。

让我们看看 AddTwo 的用法

请注意，带有指向文档页面的链接的箭头已自动添加。

不幸的是，如果我们在文档中心搜索 AddTwo ，我们会得到以下内容：

我们怎样才能使函数的摘要不被格式化？

请随意从此处下载我的代码来修改它。

感谢您的阅读。

曼努埃尔

Answer 2

我花了一段时间，但我终于完成了一个记录的 Mathematica 应用程序的编写，以帮助 Mathematica 用户编写他们记录的包。

该应用程序称为ApplicationMaker。它包含三个具有各种功能的包来帮助您创建应用程序。通过使用这些函数，您可以跳过我在之前的答案中描述的所有混乱。

如果您从我的网站下载 ApplicationMaker，您将找到一个详细的教程，向您展示如何创建完整的应用程序及其文档。

概述

要创建新应用程序，您可以通过调用 NewApplication 开始。这将创建我在前面的答案中提到的目录树。要了解有关 Mathematica 文件组织的更多信息，请点击此处。

下一步是创建包。为此，您可以调用NewPackage。此函数创建一个模板，您可以在其中编写代码。

编写完代码后，您需要调用 UpdateInit。这会更新 Mathematica 所需的 init 文件，以便您可以使用函数 Get (<<)。

此时您已准备好创建文档。只需调用CreateReferencePages，这将创建一个基本文档，您可以编辑该文档以记录应用程序中每个符号的参考页。

如果您想为您的应用程序创建指南或教程，则可以调用 NewGuide 和 NewTutorial。

完成编辑后，您需要构建应用程序，以便 Mathematica 可以使其适应其文档中心。您可以通过调用BuildApplication来完成此操作。

至此你就完成了。如果您在包的任何符号上使用信息，您应该会看到附加的箭头，引导您进入该符号的参考页面。

如果您希望共享此应用程序，您应该首先部署它。当前应用程序包含与文档中心配合使用的参考页面以及您编辑的参考页面。通过部署它，您将获得一个目录，其中仅包含应用程序运行所需的文件。

安装

您所需要做的就是将文件夹 ApplicationMaker 放入 $UserBaseDirectory/Applications/ 或 $BaseDirectory/Applications/ 中。

要开始使用，请打开文档中心并查找“ApplicationMaker”。这应该向您展示显示该包包含的所有功能的指南。在最底部您应该会看到教程的链接。

结束语

这是我为 Mathematica 构建的第一个应用程序。我将尝试不断更新软件包，以发现新的东西以使软件包变得更好。目前，我希望 ApplicationMaker 的第一个版本对任何试图记录其 Mathematica 应用程序的人都有用。

您可以在此处下载ApplicationMaker。

Answer 3

我已经下载了您的 ApplicationMaker，并正在 Windows 7 64 位上使用 Mathematica 10 对其进行测试。伟大的工作和有据可查！在使用 NewApplication 创建新应用程序时，我发现了一个小错误，需要修复我的设置。看来函数 MakeDirectory 中的变量 root 不能是长度为零的字符串（导致创建目录时出错）。我通过在原始代码中包含测试来修复此问题：

MakeDirectory[root_, start_, main_, sub_] := Module[
  {nm, ns, tmp},
  nm = Position[main, start];
  If[Length@nm != 0, nm = nm[[1, 1]]];
  If[Length@sub[[nm]] != 0,
   Do[
    tmp = 
     If[StringLength[root] != 0, 
      FileNameJoin[{root, start, sub[[nm, i]]}], 
      FileNameJoin[{start, sub[[nm, i]]}]];
    If[DirectoryQ[tmp], 
     Print[Style["Existing Directory : ", "MSG", Gray], 
      Style[tmp, "MSG", Bold]], 
     CreateDirectory[tmp];
     Print[Style["Directory Created  : ", "MSG", Blue], 
      Style[tmp, "MSG", Bold]]
     ];
    , {i, Length@sub[[nm]]}]
   ];
  Do[
   MakeDirectory[
    If[StringLength[root] != 0, FileNameJoin[{root, start}], start], 
    sub[[nm, i]], main, sub],
   {i, Length@sub[[nm]]}
   ]
  ]