If you have been using Mathematica for a while you probably have grown attached to the documentation center. There is always something new that you find in those pages. Let it be options for a function or just some examples that at some point did not seem useful to you.
It is likely that you have written packages with your specialized functions that you use all the time. Sometimes you might think of a neat example to use with your function but it is likely that it ends up being forgotten somewhere in your hard disk. If you had written it to the documentation at the moment you thought of it maybe you wouldn't be looking for it desperately later on.
For this reason I would like to know how to integrate documentation for your own functions with Mathematica's documentation center programmatically. This question is here to explore how to adapt documentation. If you have written scripts that help you do this, please share it with the community.
Wolfram's Workbench is not an acceptable solution for this question. Everything must be done with the plain installation of Mathematica. There is a couple of points that the solution should cover:
?Symbol
Search: Symbol
This is a really broad topic, I have solutions for 1, 2, and 3. I'm missing point number 4. So tell us, how do you document your functions with the documentation center?
I have added another answer. Hopefully this answer is more encouraging to users of Mathematica to write documentation pages with their packages. I think that writing documentation pages is beneficial to the application writer as well as the users of the application. If you download the package I wrote I suggest you follow the tutorial so that you can see what happens in every step. This will give you valuable experience for future projects.
Since I wrote the package there has been several people interested in this package. I have uploaded the package to Github: https://github.com/jmlopez-rod/ApplicationMaker. Please contact me if you would like to be a contributor to the repository.
To show how to create documentation that incorporates to the Documentation Center we will create a package that contains very simple functions and its documentation. Lets call our package SOPackage
. This package will be stored in a folder of the same name and such folder should be stored in either $BaseDirectory
or $UserBaseDirectory$
. The SOPakage
folder needs to have the following tree structure.
Notice that the root is the directory SOPackage
.
Now we will create a new notebook file inside SOPackage
: SOPackage.nb
. These are the contents of the notebook
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[];
Here is a screenshot of what you should see
Note that the usage messages usually format parameters in a special way. A shortcut to get this format (pointed out by @alexey-popkov) is to highlight the letter you want to format, press Command+0 (Alt+0 in windows) and enter "TI". Repeat this process for all the letters that need to be modified. Change the cell to an Initialization Cell via Cell->CellProperties->Initialization Cell
. Now we save this notebook as SOPackage.nb
. In case Mathematica did not ask you if you want to create a package because you forgot to change the cell to an initialization cell then you can go to Format->OptionInspector
. Make sure you are selecting "Options for SOPackage.nb" otherwise the option that you need to set to true will be grayed out. Now click to Notebook Options->FileOptions->AutoGeneratedPackage
and select Automatic
. Close the options window and save the file. Every time you save SOPackage.nb
the file SOPackage.m
will get updated (Do not mess with this m file).
The Kernel
directory should contain only one file: init.m
. This file needs to have the next line:
Get["SOPackage`SOPackage`"];
After this we have a working package. You can try the following to make sure that everything is working fine:
<<SOPackage`
?AddTwo
?DotTwo
DotTwo[]
DotTwo[2, 3]
Lets us start by creating the guide page. This will be the page that will show up when you type SOPackage
in the doc center. Lets start by creating a notebook and saving it under SOPackage/Documentation/English/Guides
as SOPackage_E.nb
. The reason I'm giving it the extension "_E" is because this will be an editable copy. Notice that you cannot edit any of the documents in the documentation center. Well, you can but these changes never take effect. You will probably want to modify your documentation as you build your package so it is a good idea to have a copy that you can edit. For this example we can copy the contents of the Combinatorica guide
, on the Doc center type Combinatorica/guide/CombinatoricaPackage
select all with cells, copy and paste them in your SOPackage_E.nb
file (alternatively, copy the file C:\Program Files\Wolfram Research\Mathematica\10.4\Documentation\English\Packages\Combinatorica\Documentation\English\Guides\CombinatoricaPackage.nb
or something equivalent on other OSes). Make some changes just so that you know they are the ones you are making. In my case I substituted Combinatorica with SOPackage. In the case you can cannot modify some part of a text this is what you need to do:
1: Click on the text that you cannot modify.
2: Go to Cell->Show Expression
or enter Command+Shift+E
or something equivalent in windows.
3: Look for the second argument in the Cell
expression (right before any options of the form A -> B
). This is a style name. In some cases you will see "Usage", "Notes", "ObjectName" among others. Once you locate the style of the cell that you cannot modify go click on the notebook you are editing and enter Command+Shift+E
to show back the expression.
4: Go to Format->Edit StyleSheet...
, enter the style name you saw earlier under Enter a style name:
.
5: A cell showing the style appears. Make sure this cell is selected and go to Format->Object Inspector
. Make sure it says Show option values
Selection.
6: Go to Editing Options
and set Editable
to true.
7: Modify the unmodifiable.
I suggest you first enter the name of all the styles that you want to be able to edit as I have shown in the screenshot. So far I have only changed the ones that I mentioned in step 3. Once you have them in the list select them all and set the to editable at once. Another important point is that this file can be a template. You should save this file somewhere and when you need to make a documentation just open it up, save it with another name in the right path and start copying cells from existing documentation notebooks.
It is up to you how you create this guide. For now lets just put nonsense. You'll see my screenshots. The next two files are the documentation for your functions. Copy and paste your template file to SOPackage/Documentation/English/ReferencePages/Symbols
and name the files AddTwo_E.nb
and DotTwo_E.nb
. Look for some documentation that you like, take Sin
for instance, and copy and paste the information to those files. I'll change the names just to show how they work.
The creation of the template file can surely be reduced. If someone knows how to do this programmatically please feel free to edit this section here and replace it with the code. You'll do us all a huge favor.
This file goes right under the directory SOPackage
and contains the following:
Paclet[
Name -> "SOPackage",
Version -> "0.0.1",
MathematicaVersion -> "8+",
Extensions -> {{
"Documentation",
Resources -> {
"Guides/SOPackage"
},
Language -> "English"
}}
]
There is one last thing we must do before we can have the documenation ready. We need to make all of the function documentation uneditable and we have to give it the same format as the rest of the documents. This time I wrote a script that does this. I call it MakeDoc because it will also build the index. Save this file under OSPackage
. I will break this file intwo 4 parts so that you can get an explanation.
pname = "SOPackage";
Get[pname <> "`"];
basepath = $UserBaseDirectory<>"/Applications/"<>pname<>"/Documentation/English/ReferencePages/Symbols/";
$UserBaseDirectory <> "/Applications/" <> pname <> "/Documentation/English/ReferencePages/Symbols/";
We should make sure that we restart Mathematica before doing this. First we will load the package and set the root directory of all of the function documentation. On the next step we will basically copy an paste code, we will be doing the following for each 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];
This block of code opens the editable function documentation. It saves it with the correct name. And then it changes its attributes so that its not editable and it gives it the same look as the rest of the documents. We do the same for each function. Notice that "summary" is set to the usage
message of the function. This is what we will see when we search for the function.
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];
Very important, we haven't modified the guide, this is all it takes:
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];
And finally, we create the index like this:
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];
Notice that we need to a line with AddDocumenationNotebook
for each function. After running MakeDoc.nb
the files AddTwo.nb
, DotTwo.nb
and SOPackage.nb
will be created. These files cannot be modifed. You will also see a folder named Index
. This is all binary data that contains information for the doc center. If you ever make a modification to the documentation you should run MakeDoc.nb
to make the changes take effect. Here is the document tree that we have now.
After this we should restart Mathematica and take our documentation for a ride.
This is what happens when you look for "SOPackage".
Lets look for the usage of AddTwo
Notice that an arrow with a link to the doc page was added automatically.
Unfortunately, if we search for AddTwo
in the doc center this is what we obtain:
How can we make it so that the summary for the function isn't formatted?
Feel free to modify my code by downloading it from here.
Thank you for reading.
Manuel