Wolfram mathematica 将笔记本电脑集成到Mathematica'；s文件中心

如果您已经使用Mathematica一段时间了，那么您可能已经与文档中心建立了联系。在这些页面中，你总会发现一些新的东西。让它成为一个函数的选项，或者只是一些在某些时候对您来说似乎没有用处的示例

很可能您已经编写了包含您一直在使用的专用函数的包。有时，您可能会想到一个用于函数的简洁示例，但它很可能最终被遗忘在硬盘中的某个位置。如果您在想到它的那一刻就把它写到了文档中，那么您以后就不会拼命寻找它了

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

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

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

创建指南和教程（如果认为有用）

将笔记本电脑链接到文档中心

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

• 在Mathematica笔记本中

  ？符号

• 在文档中心

  Search:Symbol

这是一个非常广泛的话题，我有1、2和3的解决方案。我错过了第四点。那么，告诉我们，您如何使用文档中心记录您的功能

---

更新 我补充了另一个答案。希望这个答案更能鼓励Mathematica的用户用他们的软件包编写文档页面。我认为编写文档页面对应用程序编写者和应用程序用户都是有益的。如果你下载了我写的软件包，我建议你按照教程去做，这样你就可以看到每一步都发生了什么。这将为您将来的项目提供宝贵的经验

Github（2014年5月24日）

---

自从我写了这个软件包，就有几个人对这个软件包感兴趣。我已将包上载到Github:。如果您想成为存储库的贡献者，请与我联系。

要演示如何创建文档，并将文档合并到文档中心，我们将创建一个包含非常简单的函数及其文档的包。让我们调用我们的包

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”。对所有需要修改的字母重复此过程。通过

单元格->单元格属性->初始化单元格

将单元格更改为初始化单元格。现在，我们将此笔记本另存为

SOPackage.nb

。如果Mathematica因为忘记将单元格更改为初始化单元格而未询问您是否要创建包，则可以转到

格式->选项Inspector

。确保您正在选择“Options for SOPackage.nb”，否则需要设置为true的选项将灰显。现在点击

笔记本选项->文件选项->自动生成包

，然后选择

自动

。关闭“选项”窗口并保存文件。每次保存

SOPackage.nb

时，文件

SOPackage.m

都会更新（不要弄乱此m文件）

Kernel

目录应该只包含一个文件：

init.m

。此文件需要有下一行：

Get["SOPackage`SOPackage`"];

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

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

在准备好文件之前，我们还必须做最后一件事。我们需要使所有函数文档都不可编辑，并且我们必须为其提供与其他文档相同的格式。这次我写了一个脚本来实现这一点。我称之为MakeDoc，因为它还将构建索引。将此文件保存在

OSPackage

下。我将把这个文件分成两部分，这样你就可以得到解释

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

非常重要，我们没有修改指南，仅此而已：

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];

snname:=“SOPackage”；
nb=记事本打开[导轨snname“_E.nb”]；
NotebookSave[nb，导轨名称“.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];

indir=$UserBaseDirectory”/Applications/“pname”/Documentation/English/Index；
如果[FileNames[indir]！={}，则删除目录[indir，DeleteContents->True]；
ind=DocumentationSearch`NewDocumentationNotebookIndexer[indir]；
DocumentationSearch`AddDocumentationNotebook[ind，basepath“AddTwo.nb”]；
DocumentationSearch`AddDocumentationNotebook[ind，basepath“dottow.nb]”；
DocumentationSearch`CloseDocumentationNotebookIndexer[ind]；

请注意，我们需要为每个函数添加一行

AddDocumenationNotebook

。运行

MakeDoc.nb

文件

Ad之后
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];

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]]}
   ]
  ]