Skip to main content

notebooks - How to write documentation in Wolfram Style?


Rather than craft my own stylesheets for documentation, I'd like to emulate (copy? ape? borrow?) the Wolfram style. Here is a very small example (type this in the help-box, which you get by pressing F1)


Quaternions/ref/UnitQuaternionQ

Here is a very large example


ContourPlot3D

I have zero experience creating styles, and I have only the most foggy understanding of how Notebooks work. I have gotten this far: If I scrape over the orange-and-yellow text at the top of the UnitQuaternionQ example, the cell just underneath the heading, then press Command-Shift-E or use the Cell>Show Expression menu item, then I see this magnificent bouillabaisse:


Cell[BoxData[GridBox[{

   {"", Cell[TextData[{
     Cell[BoxData[
      RowBox[{"UnitQuaternionQ", "[", 
       StyleBox["q", "TI"], "]"}]], "InlineFormula"],
     "\[LineSeparator]gives ",
     Cell[BoxData[
      TemplateBox[{Cell["True"],"paclet:ref/True"},
       "RefLink",
       BaseStyle->"InlineFormula"]], "InlineFormula"],
     " if ",

     Cell[BoxData[
      StyleBox["q", "TI"]], "InlineFormula"],
     " is a unit quaternion and ",
     Cell[BoxData[
      TemplateBox[{Cell["False"],"paclet:ref/False"},
       "RefLink",
       BaseStyle->"InlineFormula"]], "InlineFormula"],
     " otherwise."
    }]]}
  }]], "Usage",

 GridBoxOptions->{
 GridBoxBackground->{
  "Columns" -> {{None}}, "ColumnsIndexed" -> {}, "Rows" -> {{None}}, "RowsIndexed" -> {}}},
 CellID->16193]

This gives me a lot of clues, but also a large number of things to look up, understand separately, and then piece back together, namely Cell, GridBox, TextData, BoxData, RowBox, StyleBox, TemplateBox, paclets as URIs, and everything they depend on. I also find out that when I paste that expression into a new notebook and do Command-Shift-E, I get errors, most of which imply that there is a missing stylesheet. From this I infer that notebooks have a secret, implicit "style sheet" attribute, but I don't know how to set it or get it in a general way. When my mouse-focus is in the help box, the Format menu does not contain an obvious way for me to snip, copy, borrow, ape, or otherwise access the style sheet.


I tried looking for an author's guide in the documentation, but a few quick searches didn't turn up anything on-point.



Answer



I have put to the test Leonid's second suggestion, ApplicationMaker by jmlopez, I have shared out an extended example here. It's a little library for rotation quaternions and rigid-body dynamics that illustrates the Dzhanybekhov effect. I created it from scratch by straight reading of the documents provided with ApplicationMaker (most of it in a very nice local cigar lounge, but that's another story :) Here are my major findings:


You do NewPackage and get a notebook for writing your package (ApplicationMaker will make the .m file for you from this notebook). Don't get even slightly fancy with usage messages in here! In my first attempt, I tried something as little as setting the arguments for function forms in italics, and it caused a cascade of crap to happen later when I did BuildApplication and DeployApplication. I had to rekeyboard all my ::usage messages because even one stray invisible Italic tag caused massive downstream pain -- missing styles, all kinds of StyleBox noise copied to the reference pages, many more goobers I didn't even look into.



Other than that, it seemed to work well with MMA 9, even though it was written for MMA 8. Huge kudos to jmlopez for working this out. While it's not perfect, it's such a great start that I will certainly use it in the future.


I did not complete the documentation for my sample in the interests of getting this answer out quickly. Another couple of findings (really reminders for me) are:


Proper documentation is a LOT of work. It easily outstrips the effort of writing the code by factors of 2 to 10. Even for my tiny example, it would probably take me several more days to get it to professionally presentable level.


HOWEVER it is very valuable work! The effort of writing documentation and thinking about how someone else would try to understand this tiny library made me improve it by refactoring and redesigning several times. A professionally presentable API isn't even fully DESIGNED before it's DOCUMENTED with a skeptical, third-party audience in mind! Just do it.


Comments

Post a Comment

Popular posts from this blog

mathematical optimization - Minimizing using indices, error: Part::pkspec1: The expression cannot be used as a part specification

I want to use Minimize where the variables to minimize are indices pointing into an array. Here a MWE that hopefully shows what my problem is. vars = u@# & /@ Range[3]; cons = Flatten@ { Table[(u[j] != #) & /@ vars[[j + 1 ;; -1]], {j, 1, 3 - 1}], 1 vec1 = {1, 2, 3}; vec2 = {1, 2, 3}; Minimize[{Total@((vec1[[#]] - vec2[[u[#]]])^2 & /@ Range[1, 3]), cons}, vars, Integers] The error I get: Part::pkspec1: The expression u[1] cannot be used as a part specification. >> Answer Ok, it seems that one can get around Mathematica trying to evaluate vec2[[u[1]]] too early by using the function Indexed[vec2,u[1]] . The working MWE would then look like the following: vars = u@# & /@ Range[3]; cons = Flatten@{ Table[(u[j] != #) & /@ vars[[j + 1 ;; -1]], {j, 1, 3 - 1}], 1 vec1 = {1, 2, 3}; vec2 = {1, 2, 3}; NMinimize[ {Total@((vec1[[#]] - Indexed[vec2, u[#]])^2 & /@ R...
Post a Comment
Read more

functions - Get leading series expansion term?

Given a function f[x] , I would like to have a function leadingSeries that returns just the leading term in the series around x=0 . For example: leadingSeries[(1/x + 2)/(4 + 1/x^2 + x)] x and leadingSeries[(1/x + 2 + (1 - 1/x^3)/4)/(4 + x)] -(1/(16 x^3)) Is there such a function in Mathematica? Or maybe one can implement it efficiently? EDIT I finally went with the following implementation, based on Carl Woll 's answer: lds[ex_,x_]:=( (ex/.x->(x+O[x]^2))/.SeriesData[U_,Z_,L_List,Mi_,Ma_,De_]:>SeriesData[U,Z,{L[[1]]},Mi,Mi+1,De]//Quiet//Normal) The advantage is, that this one also properly works with functions whose leading term is a constant: lds[Exp[x],x] 1 Answer Update 1 Updated to eliminate SeriesData and to not return additional terms Perhaps you could use: leadingSeries[expr_, x_] := Normal[expr /. x->(x+O[x]^2) /. a_List :> Take[a, 1]] Then for your examples: leadingSeries[(1/x + 2)/(4 + 1/x^2 + x), x] leadingSeries[Exp[x], x] leadingSeries[(1/x + 2 + (1 - 1/x...
Post a Comment
Read more

What is and isn't a valid variable specification for Manipulate?

I have an expression whose terms have arguments (representing subscripts), like this: myExpr = A[0] + V[1,T] I would like to put it inside a Manipulate to see its value as I move around the parameters. (The goal is eventually to plot it wrt one of the variables inside.) However, Mathematica complains when I set V[1,T] as a manipulated variable: Manipulate[Evaluate[myExpr], {A[0], 0, 1}, {V[1, T], 0, 1}] (*Manipulate::vsform: Manipulate argument {V[1,T],0,1} does not have the correct form for a variable specification. >> *) As a workaround, if I get rid of the symbol T inside the argument, it works fine: Manipulate[ Evaluate[myExpr /. T -> 15], {A[0], 0, 1}, {V[1, 15], 0, 1}] Why this behavior? Can anyone point me to the documentation that says what counts as a valid variable? And is there a way to get Manpiulate to accept an expression with a symbolic argument as a variable? Investigations I've done so far: I tried using variableQ from this answer , but it says V[1...
Post a Comment
Read more