Take the 2-minute tour ×
Mathematica Stack Exchange is a question and answer site for users of Mathematica. It's 100% free, no registration required.

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.

share|improve this question
1  
This might be the answer: wolfram.com/products/workbench –  Reb.Cabin May 10 at 16:56
    
I'm leaving the question up in case someone provides an answer that is independent of workbench. –  Reb.Cabin May 10 at 16:59
5  
A couple of possibly useful links: David Bailey's account on documentation, and this question / answers. –  Leonid Shifrin May 10 at 18:26
    
Leonid's second suggestion, integrating notebooks to documentation center, is a complete answer. stackoverflow.com/questions/6574710/… –  Reb.Cabin May 11 at 15:21
3  
May I then suggest that after you make use of it, you could perhaps write an answer here, summarizing both that previous answer and your experiences using it. In this way, this might be more useful than just copy - pasting that answer here. –  Leonid Shifrin May 11 at 15:48

1 Answer 1

up vote 5 down vote accepted

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.

share|improve this answer
    
Thank you for sharing your experience and bringing this topic up. This must be also useful to me someday. I totally agree that it is very valuable to write a well-organized documentation. –  Leo Fang May 23 at 2:10
    
It's great it exists but it's far from perfect and should be rewritten. In my case it didn't even work, and content gets generated in a very non-natural way, so I didn't learn anyithng about it while studying the source. If somebody wants to contribute to this, please contact me (author himself or herself doesn't have time for that). Proper documentation should not be a lot of work: in Mathematica it's just a bunch of examples rubricated in a certain way, it works wonderfully, and it should not be difficult to create at all. –  Akater May 23 at 10:16
    
For me, examples are the crux of the documentation. Users should be able to learn my library from the examples alone, with the formal description mostly for back-checking the abstraction the user mentally develops from the examples. Imagining how the user will read the examples, often leads to revising the library itself. It's similar to writing unit tests in ordinary software development. The examples should be a minimal set that illustrates everything important the functions do and don't do, especially edge cases. (That's why I say it's a lot of work -- it generates refactoring of the code) –  Reb.Cabin May 23 at 13:03
    
@Akater I'll be happy to contribute to your rewrite of ApplicationMaker as time allows me to do. –  Reb.Cabin May 23 at 13:04
    
@Reb.Cabin github.com/akater/ApplicationMaker Feel free to email or Jabber me, it's all in the profile. –  Akater May 24 at 0:54

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.