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

如果您一直在使用Mathematica，您可能已经连接到文档中心。 在这些页面中总会找到新的东西。 让它成为一个函数的选项，或者只是一些例子，在某些时候对你看起来并不有用。

您可能已经编写了包含您始终使用的专用函数的软件包。 有时候你可能会想到一个用于你的函数的简单例子，但它很可能最终会被遗忘在硬盘的某个地方。 如果你在想到它的时候把它写到了文档中，那么以后你可能不会在寻找它。

出于这个原因，我想知道如何以编程方式将自己的功能文档与Mathematica的文档中心集成在一起。 这个问题是在这里探索如何适应文档。 如果您编写的脚本可以帮助您做到这一点，请与社区分享。

对于这个问题，Wolfram's Workbench不是一个可接受的解决方案。 一切都必须通过Mathematica的简单安装完成。 解决方案应该包括几点：

为函数创建文档（最好是模板）。

创建指南和教程（如果它们被认为有用）。

将笔记本连接到文档中心。

创建在不同环境中正确显示的“使用”消息。

在Mathematica笔记本中?Symbol

在文档中心Search: Symbol

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

---

更新

我添加了另一个答案。 希望这个答案对Mathematica的用户来说更令人鼓舞，可以用他们的软件包编写文档页面。 我认为编写文档页面对应用程序编写者以及应用程序的用户都有好处。 如果你下载了我写的软件包，我建议你按照教程，以便你可以看到每一步发生了什么。 这将为您未来的项目提供宝贵的经验。

Github（2014年5月24日）

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

---

为了展示如何创建与文档中心结合的文档，我们将创建一个包含非常简单的函数和文档的软件包。 让我们打电话给我们的包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将单元更改为Cell->CellProperties->Initialization Cell 。 现在我们将该笔记本保存为SOPackage.nb 。 如果Mathematica没有问您是否想创建一个包，因为您忘记将单元更改为初始化单元，则可以转到Format->OptionInspector 。 确保你选择了“SOPackage.nb的选项”，否则你需要设置为true的选项将变灰。 现在点击Notebook Options->FileOptions->AutoGeneratedPackage并选择Automatic 。 关闭选项窗口并保存文件。 每次保存SOPackage.nb文件SOPackage.m都会得到更新（不要SOPackage.m这个m文件）。

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

Get["SOPackage`SOPackage`"];

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

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

文档

让我们从创建指南页面开始。 这将是在文档中心键入SOPackage时显示的页面。 让我们开始创建一个笔记本，并将其作为SOPackage_E.nb保存在SOPackage/Documentation/English/Guides SOPackage_E.nb 。 我给它扩展名为“_E”的原因是因为这将是一个可编辑的副本。 请注意，您无法编辑文档中心的任何文档。 那么，你可以但这些改变从未生效。 在构建软件包时，您可能会想要修改文档，因此最好拥有一个可以编辑的副本。 对于这个例子，我们可以复制Combinatorica guide的内容，在Doc中心类型Combinatorica/guide/CombinatoricaPackage选择所有包含单元格的文件，将它们复制并粘贴到SOPackage_E.nb文件中（或者复制文件C:Program FilesWolfram ResearchMathematica10.4DocumentationEnglishPackagesCombinatoricaDocumentationEnglishGuidesCombinatoricaPackage.nb或其他操作系统上的等价物）。 做一些改变，让你知道他们是你正在做的。 在我的情况下，我用SOPackage替换了Combinatorica。 在这种情况下，您无法修改文本的某些部分，这是您需要执行的操作：

1：点击您无法修改的文字。

2：转到单元格Cell->Show Expression或在窗口中输入Command+Shift+E或其他等效物。

3：在Cell表达式中寻找第二个参数（就在A -> B形式的任何选项之前）。 这是一个样式名称。 在某些情况下，您会看到“Usage”，“Notes”，“ObjectName”等。 一旦找到不能修改的单元格的样式，请单击正在编辑的笔记本并输入Command+Shift+E以显示表达式。

4：转到Format->Edit StyleSheet... ，输入您在前面Enter a style name:下看到Enter a style name: 。

5：显示样式的单元格出现。 确保选中此单元格并转到Format->Object Inspector 。 确保它说Show option values选择。

6：进入Editing Options和设置Editable为true。

7：修改不可修改。

我建议您首先输入您想要编辑的所有样式的名称，如我在截图中所示。 到目前为止，我只改变了我在步骤3中提到的那些。一旦你在列表中选择了它们，并将它们全部设置为可编辑。 另一个重要的一点是，这个文件可以是一个模板。 您应该将该文件保存到某个位置，并且在需要创建文档时只需将其打开，然后将其另存为正确路径并从现有文档笔记本中复制单元格。

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

模板文件的创建肯定可以减少。 如果有人知道如何以编程方式执行此操作，请随时在此处编辑此部分，并用代码替换它。 你会为我们做一个很大的忙。

PacletInfo.m

该文件位于SOPackage目录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];

这段代码打开可编辑的功能文档。 它用正确的名字保存它。 然后它改变它的属性，使其不可编辑，并使其与其他文档具有相同的外观。 我们对每个功能都做同样的事情。 请注意，“摘要”被设置为功能的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 ，我们可以得到：

我们怎样才能使它的功能摘要没有格式化？

随意从这里下载它来修改我的代码。

谢谢你的阅读。

曼努埃尔

---

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

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

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

概观

通过调用NewApplication来创建一个新的应用程序。 这创建了我在前面的答案中提到的目录树。 要了解更多关于Mathematica的文件组织的信息，请点击这里。

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

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

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

如果你想为你的应用程序创建一个指南或教程，那么你可以调用NewGuide和NewTutorial 。

完成编辑后，您需要构建应用程序，以便Mathematica可以将其应用于其文档中心。 你可以通过调用BuildApplication做到这BuildApplication 。

此时你已完成。 如果您在包装的任何符号上使用Information ，您应该看到一个附加的箭头，将您引导至该符号的参考页面。

如果你想分享这个应用程序，你应该首先部署它。 当前应用程序包含与文档中心和您编辑的参考页面一起工作。 通过部署它，您可以获得仅包含必要文件的目录，以便您的应用程序能够正常工作。

安装

您只需将文件夹ApplicationMaker放入$UserBaseDirectory/Applications/或$BaseDirectory/Applications/ 。

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

最后的话

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

您可以在这里下载ApplicationMaker。

---

我已经下载了您的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]]}
   ]
  ]

链接地址: http://www.djcxy.com/p/6049.html

上一篇: Integrating notebooks to Mathematica's documentation center

下一篇: Mathematica: Function Documentation