ノートブックを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

しばらく時間がかかりましたが、Mathematicaユーザーが文書化されたパッケージを書くのを助けるために、文書化されたMathematicaアプリケーションを書き終えました。

このアプリケーションはApplicationMakerと呼ばれます。これには、アプリケーションの作成に役立つさまざまな機能を備えた3つのパッケージが含まれています。これらの関数を使用することで、以前の回答で説明したすべての混乱をスキップできます。

私のウェブサイトからApplicationMakerをダウンロードすると、そのドキュメントを使用して完全なアプリケーションを作成する方法を示す詳細なチュートリアルが見つかります。

概要概要

新しいアプリケーションを作成するには、まずNewApplicationを呼び出します。これにより、前の回答で説明したディレクトリツリーが作成されます。 Mathematicaのファイル構成の詳細を見つけるには、 ここ をクリックしてください。

次のステップは、パッケージを作成することです。そのためには、NewPackageを呼び出します。この関数は、コードを記述するテンプレートを作成します。

コードの記述が終了したら、UpdateInitを呼び出す必要があります。これにより、Mathematicaが必要とするinitファイルが更新され、関数Get (<<)を使用できるようになります。

この時点で、ドキュメントを作成する準備が整いました。 CreateReferencePagesを呼び出すだけで、アプリケーションの各シンボルの参照ページを文書化するために編集できる基本的な文書が作成されます。

アプリケーションのガイドまたはチュートリアルを作成する場合は、NewGuideおよびNewTutorialを呼び出すことができます。

編集が終わったら、Mathematicaがドキュメントセンターに適応できるようにアプリケーションを構築する必要があります。これを行うには、BuildApplicationを呼び出します。

この時点で完了です。パッケージのシンボルのいずれかでInformationを使用すると、そのシンボルのリファレンスページにつながる矢印が追加されているはずです。

このアプリケーションを共有したい場合は、最初にデプロイする必要があります。現在のアプリケーションには、ドキュメントセンターで機能するリファレンスページと編集したリファレンスページが含まれています。それをデプロイすることにより、アプリケーションが機能するために必要なファイルのみを含むディレクトリを取得します。

Installation

ApplicationMakerフォルダを$UserBaseDirectory/Applications/または$BaseDirectory/Applications/にドロップするだけです。

開始するには、ドキュメントセンターを開き、「ApplicationMaker」を探します。これにより、パッケージに含まれるすべての機能を示すガイドが表示されます。一番下にチュートリアルへのリンクが表示されます。

最後の言葉

これは私がMathematica用に作った最初のアプリケーションです。パッケージをより良くするための新しいことを発見するにつれて、私はパッケージを更新し続けるように努めます。今のところ、この最初のバージョンのApplicationMakerが、Mathematicaアプリケーションを文書化しようとしている人に役立つことを願っています。

ApplicationMakerをダウンロードできます ここ 。

Answer 2

ドキュメントセンターに組み込むドキュメントを作成する方法を示すために、非常に単純な関数とそのドキュメントを含むパッケージを作成します。パッケージを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 （（Alt+0 Windowsで）そして「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という1つのファイルのみを含める必要があります。このファイルには次の行が必要です。

Get["SOPackage`SOPackage`"];

この後、作業パッケージができました。次のことを試して、すべてが正常に機能していることを確認できます。

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

ドキュメンテーション

ガイドページを作成することから始めましょう。これは、ドキュメントセンターでSOPackageと入力したときに表示されるページになります。ノートブックを作成し、それをSOPackage/Documentation/English/Guidesの下にSOPackage_E.nbとして保存することから始めましょう。拡張子「_E」を付ける理由は、これが編集可能なコピーになるためです。ドキュメントセンターでは、どのドキュメントも編集できないことに注意してください。できますが、これらの変更は有効になりません。パッケージをビルドするときにドキュメントを変更することをお勧めします。そのため、編集可能なコピーを用意しておくことをお勧めします。この例では、Combinatorica guideの内容をコピーし、ドキュメントセンターでCombinatorica/guide/CombinatoricaPackageと入力して、セルを含むすべてを選択し、それらをコピーしてSOPackage_E.nbファイルに貼り付けます（または、ファイルC:\Program Files\Wolfram Research\Mathematica\10.4\Documentation\English\Packages\Combinatorica\Documentation\English\Guides\CombinatoricaPackage.nbまたは他のOSの同等のものをコピーします）。それらがあなたが行っているものであることがわかるように、いくつかの変更を加えます。私の場合、CombinatoricaをSOPackageに置き換えました。テキストの一部を変更できない場合は、次のようにする必要があります。

1：変更できないテキストをクリックします。

2：Cell->Show Expressionに移動するか、WindowsでCommand+Shift+Eまたは同等のものを入力します。

3：Cell式の2番目の引数を探します（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で説明したものだけを変更しました。リストにそれらが表示されたら、それらをすべて選択し、を一度に編集可能に設定します。もう1つの重要な点は、このファイルをテンプレートにすることができるということです。このファイルをどこかに保存する必要があります。ドキュメントを作成する必要がある場合は、ファイルを開いて、正しいパスに別の名前で保存し、既存のドキュメントノートブックからセルのコピーを開始します。

このガイドをどのように作成するかはあなた次第です。今のところ、ナンセンスを入れましょう。私のスクリーンショットが表示されます。次の2つのファイルは、関数のドキュメントです。テンプレートファイルをコピーして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"
}}
]

ドキュメントを準備する前に、最後にやらなければならないことが1つあります。すべての関数ドキュメントを編集不可にする必要があり、残りのドキュメントと同じ形式にする必要があります。今回は、これを行うスクリプトを作成しました。インデックスも作成するので、MakeDocと呼びます。このファイルをOSPackageの下に保存します。説明が得られるように、このファイルを2つの4つの部分に分割します。

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を検索すると、次のようになります。

関数の要約がフォーマットされないようにするにはどうすればよいですか？

here からダウンロードして、コードを自由に変更してください。

読んでくれてありがとう。

マヌエル

Answer 3

ApplicationMakerをダウンロードし、Windows 764ビットでMathematica10を使用してテストしています。素晴らしい仕事と十分に文書化されています！ NewApplicationを使用して新しいアプリケーションを作成するときに、セットアップの修正が必要な小さなエラーを発見しました。関数rootの変数MakeDirectoryは、長さがゼロの文字列にすることはできないようです（ディレクトリの作成でエラーが発生します）。元のコードにテストを含めることでこれを修正しました。

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