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

如果您一直在使用Mathematica ，那么您可能已经连接到文档中心。 在这些页面中总会有新的东西。 让它成为一个function的选项，或者只是一些例子，在某些时候对你来说似乎没有用处。

您可能已经用自己的专业function编写了一些软件包，而且这些软件包一直都在使用。 有时候你可能会想到一个简单的例子来使用你的函数，但它可能最终被遗忘在你的硬盘的某个地方。 如果在你想到这个时刻把它写到文档中，那么以后你可能不会再那么拼命了。

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

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

  1. 为函数创build文档（最好是模板）。
  2. 创build指南和教程（如果他们被认为是有用的）。
  3. 将笔记本连接到文档中心。
  4. 创build在不同环境下正确显示的“使用”消息。
    • 在Mathematica笔记本?Symbol
    • 在文档中心Search: Symbol

这是一个非常广泛的话题，我有1,2和3的解决scheme。我缺less第4点。所以告诉我们，你如何用文档中心logging你的function？

更新

我已经添加了另一个答案。 希望这个答案更令Mathematica的用户能够用他们的包编写文档页面。 我认为编写文档页面对于应用程序编写者以及应用程序的用户是有利的。 如果你下载我写的软件包，我build议你按照教程，以便你可以看到每一步发生的事情。 这会给你未来项目的宝贵经验。

Github（2014年5月24日）

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

为了展示如何创build与文档中心结合的文档，我们将创build一个包含非常简单的函数和文档的软件包。 让我们打电话给我们的包SOPackage 。 这个包将被存储在一个同名的文件夹中，这个文件夹应该存储在$BaseDirectory或$UserBaseDirectory$ 。 SOPakage文件夹需要具有以下树形结构。

在这里输入图像说明

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

SOPackage

现在我们将在SOPackage创build一个新的笔记本文件： 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[];

这里是你应该看到的一个截图

SOPackage

请注意，使用消息通常以特殊方式格式化参数。 获得这种格式的快捷方式（由@ alexey-popkov指出）是突出显示要格式化的字母，按下Command + 0 （Windows +中的Alt + 0 ）并input“TI”。 对所有需要修改的字母重复这个过程。 通过Cell->CellProperties->Initialization Cell将单元更改为Cell->CellProperties->Initialization Cell 。 现在我们把这个笔记本保存为SOPackage.nb 。 如果Mathematica没有问你是否想创build一个包，因为你忘记把单元格更改为初始化单元，那么你可以去Format->OptionInspector 。 确保你select了“SOPackage.nb选项”，否则你需要设置为true的选项将变灰。 现在点击Notebook Options->FileOptions->AutoGeneratedPackage并selectAutomatic 。 closures选项窗口并保存文件。 每次保存SOPackage.nb文件SOPackage.m将得到更新（不要惹这个m文件）。

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

 Get["SOPackage`SOPackage`"];

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

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

测试

文档

让我们从创build指南页面开始。 这将是在文档中心键入SOPackage时显示的页面。 让我们开始创build一个笔记本电脑，并保存在SOPackage/Documentation/English/Guides作为SOPackage_E.nb 。 我给它扩展名为“_E”的原因是因为这将是一个可编辑的副本。 请注意，您不能编辑文档中心的任何文档。 那么，你可以，但这些变化永远不会生效。 在构build软件包时，您可能需要修改文档，因此最好有一个可以编辑的副本。 对于这个例子，我们可以复制Combinatorica guide的内容，在Doc中心types的Combinatorica/guide/CombinatoricaPackageselect所有单元格，将它们复制并粘贴到SOPackage_E.nb文件中（或者复制文件C:\Program Files\Wolfram Research\Mathematica\10.4\Documentation\English\Packages\Combinatorica\Documentation\English\Guides\CombinatoricaPackage.nb或其他操作系统上的等价物）。 做一些改变，让你知道他们是你正在做的。 在我的情况下，我用SOPackagereplace了Combinatorica。 在这种情况下，你不能修改文本的某些部分，这是你需要做的：

1：点击你不能修改的文字。

在这里输入图像说明

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

在这里输入图像说明

3：查找Cellexpression式中的第二个参数（就在A -> Bforms的任何选项之前）。 这是一个风格的名字。 在某些情况下，您会看到“用法”，“注释”，“对象名称”等等。 一旦find不能修改的单元格的样式，请单击正在编辑的笔记本，然后inputCommand+Shift+E以显示expression式。

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

在这里输入图像说明

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

6：转到“ Editing Options并将“ Editable Editing Options设置为true。

在这里输入图像说明

7：修改不可修改。

在这里输入图像说明

我build议你先input你想要编辑的所有样式的名称，就像我在屏幕截图中显示的那样。 到目前为止，我只是改变了我在步骤3中提到的那些。一旦你在列表中select了它们，并将它们全部设置为可编辑。 另一个重要的一点是，这个文件可以是一个模板。 你应该把这个文件保存在某个地方，当你需要创build一个文档时，只需打开它，用另一个名字保存在正确的path中，然后从现有的文档笔记本复制单元格。

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

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

PacletInfo.m

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

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

在准备好文件之前，还有最后一件事情要做。 我们需要使所有的function文件都是不可编辑的，我们必须给它与其他文件相同的格式。 这一次，我写了一个脚本来做到这一点。 我把它叫做MakeDoc，因为它也会build立索引。 将此文件保存在OSPackage下。 我将把这个文件分成两部分，这样你就可以得到解释。 

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

我们应该确保在这之前重新启动Mathematica。 首先，我们将加载包并设置所有function文档的根目录。 下一步我们将基本上复制一个粘贴代码，我们将为每个函数做下面的事情。 

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

这段代码打开可编辑的function文档。 它用正确的名字保存它。 然后它改变它的属性，使其不可编辑，并使其与文档的其余部分具有相同的外观。 我们对每个function都做同样的事情。 请注意，“摘要”被设置为该函数的usage信息。 这是我们在searchfunction时会看到的。 

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

最后，我们创build这样的索引： 

 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后，将创buildAddTwo.nb ， DotTwo.nb和SOPackage.nb文件。 这些文件不能被修改。 您还将看到一个名为Index的文件夹。 这是包含文档中心信息的所有二进制数据。 如果您对文档进行了修改，则应运行MakeDoc.nb以使更改生效。 这是我们现在拥有的文档树。

在这里输入图像说明

在此之后，我们应该重新启动Mathematica，并采取我们的文档。

这是当你寻找“SOPackage”时发生的事情。

在这里输入图像说明

让我们来看看AddTwo的用法

在这里输入图像说明

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

不幸的是，如果我们在文档中心searchAddTwo ，我们可以得到：

在这里输入图像说明

我们怎样才能使这个函数的摘要没有格式化呢？

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

感谢您的阅读。

曼努埃尔

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

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

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

概观

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

下一步是创build包。 为此，你叫NewPackage 。 这个函数在你写代码的地方创build一个模板。

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

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

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

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

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

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

安装

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

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

最后的话

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

您可以在这里下载ApplicationMaker。

我已经下载了您的ApplicationMaker，并在Windows 7 64位上使用Mathematica 10进行testing。 伟大的工作，有据可查！ 当使用NewApplication创build一个新的应用程序时，我发现了一个小错误，需要修改我的设置。 看起来， MakeDirectory函数中的variablesroot不能是长度为零的string（在创build目录时会导致错误）。 我通过在您的原始代码中包含testing来解决这个问题： 

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