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

Question

如果您已经使用Mathematica一段时间,您可能已经加入了文档中心.在这些页面中总会找到新的东西.让它成为一个函数的选项,或者只是一些在某些时候似乎对你没用的例子.

您可能已经编写了包含您始终使用的专用函数的软件包.有时您可能会想到一个与您的功能一起使用的简洁示例,但很可能它最终被遗忘在硬盘中的某个地方.如果您在考虑它的那一刻就将其写入文档,那么您可能不会在以后拼命寻找它.

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

对于这个问题,Wolfram的Workbench不是一个可接受的解决方案.一切都必须通过Mathematica的简单安装完成.解决方案应涵盖以下几点:

1. 为函数创建文档(最好是模板).
2. 创建指南和教程(如果他们认为有用).
3. 将笔记本电脑链接到文档中心.
4. 创建在不同环境中正确显示的"使用"消息.
   • 在Mathematica笔记本中 ?Symbol
   • 在文档中心 Search: Symbol

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

---

更新

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

Github(2014年5月24日)

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

Answer 1

为了展示如何创建包含在文档中心的文档,我们将创建一个包含非常简单的函数及其文档的包.让我们打电话给我们的包SOPackage.此包将存储在同名文件夹中,此类文件夹应存储在$BaseDirectory或中$UserBaseDirectory$.该SOPakage文件夹需要具有以下树结构.

请注意,root是目录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(Alt+0在窗口中)并输入"TI".对需要修改的所有字母重复此过程.通过将单元格更改为初始化单元格Cell->CellProperties->Initialization Cell.现在我们把这个笔记本保存为SOPackage.nb.如果Mathematica没有问您是否要创建包,因为您忘记将单元格更改为初始化单元格,那么您可以转到Format->OptionInspector.确保选择"SOPackage.nb选项",否则您需要设置为true的选项将显示为灰色.现在点击Notebook Options->FileOptions->AutoGeneratedPackage并选择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 guideDoc中心类型的内容,Combinatorica/guide/CombinatoricaPackage选择all with cells,将它们复制并粘贴到您的SOPackage_E.nb文件中(或者,复制文件C:\Program Files\Wolfram Research\Mathematica\10.4\Documentation\English\Packages\Combinatorica\Documentation\English\Guides\CombinatoricaPackage.nb或其他操作系统上的等效文件).进行一些更改,以便您知道它们就是您正在制作的.在我的情况下,我用SOPackage替换了Combinatorica.如果您无法修改文本的某些部分,则需要执行以下操作:

1:单击无法修改的文本.

2:在Windows中转到Cell->Show Expression或输入Command+Shift+E等效的东西.

3:在Cell表达式中查找第二个参数(在表单的任何选项之前A -> B).这是一个样式名称.在某些情况下,您将看到"Usage","Notes","ObjectName"等.找到无法修改的单元格样式后,单击要编辑的笔记本,然后输入Command+Shift+E以显示表达式.

4:转到Format->Edit StyleSheet...,输入您之前看到的样式名称Enter a style name:.

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

6:转到Editing Options并设置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.这是包含doc中心信息的所有二进制数据.如果您对文档进行了修改,则应运行MakeDoc.nb以使更改生效.这是我们现在拥有的文档树.

在此之后,我们应该重新启动Mathematica并获取我们的文档.

当你寻找"SOPackage"时会发生这种情况.

让我们来看看用法 AddTwo

请注意,自动添加了带有指向doc页面链接的箭头.

不幸的是,如果我们AddTwo在doc中心搜索,这就是我们获得的:

我们如何才能使函数的摘要不格式化？

从这里下载它可以随意修改我的代码.

谢谢你的阅读.

曼努埃尔

Answer 2

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

这个应用程序被调用ApplicationMaker.它包含三个包含各种功能的包,可帮助您创建应用程序.通过使用这些功能,您可以跳过我在之前的答案中描述的所有混乱.

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

概观

要创建新的应用程序,请先致电NewApplication.这将创建我在上一个答案中提到的目录树.要了解有关Mathematica文件组织的更多信息,请单击此处.

下一步是创建包.为此你打电话NewPackage.此函数创建一个用于编写代码的模板.

编写完代码后,需要调用UpdateInit.这会更新Mathematica需要的init文件,以便您可以使用该功能Get (<<).

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

如果您想为您的应用程序创建指南或教程,那么您可以打电话给NewGuide和NewTutorial.

完成编辑后,您需要构建应用程序,以便Mathematica可以将其调整到文档中心.你通过电话来做到这一点BuildApplication.

此时你已经完成了.如果您Information在包装的任何符号上使用,您应该看到附加的箭头,引导您到该符号的参考页面.

如果您希望共享此应用程序,则应首先进行部署.当前应用程序包含与文档中心一起使用的参考页面以及您编辑的参考页面.通过部署它,您将获得一个目录,其中只包含应用程序所需的文件.

安装

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

要开始打开文档中心并查找"ApplicationMaker".这应该向您显示指南,其中显示了包中包含的所有功能.在最底部,您应该看到教程的链接.

最后的话

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

您可以在此处下载ApplicationMaker .