workbench - How to make notebooks suitable for the Documentation Center?

Normally, documentation meant to be integrated into the Documentation Center is built from special source notebooks.

According to the Workbench documentation, it should also be possible to use alternative formats. Just create the notebooks and put them at the specified location. They will be copied over during documentation build and they will get a suitable URI for the Documentation Center.

I tried this and it works, but there are some problems. The biggest one is that pressing the Reload button opens the notebooks in a standard window instead of in a documentation window.

How should a notebook be prepared so that it properly integrates into the Documentation Center and is well-behaved there?

This question is specifically about simple notebooks that do not go through the documentation build process.

As a first test, I was simply building a license page, for which there is no standard template. But eventually I would like to use this for documentation in alternative formats, as I won't always have time to create standard format documentation.

---

"What have you tried?"

The toolbar source can be examined using

FrontEndResource["FEExpressions", "HelpViewerToolbar"]

The button seems to invoke the Revert front end token, i.e. it's similar to (the same as?) File -> Revert... This explains the behaviour I see but I still don't know why normal documentation notebooks don't behave this way.

I tried taking StyleDefinitions (which also adds the toolbar docked cell) and TaggingRules from a normally built doc notebook and trasferring them to my custom notebook. I manually edited the URIs to match. The Revert button still re-opens the notebook in a new window.

Note that I am not asking for adding the help toolbar to the notebook. This can indeed by accomplished by ensuring that the notebook or its stylesheet has DockedCells -> FEPrivate`FrontEndResource["FEExpressions", "HelpViewerToolbar"]. But the Reload button will still open a new window which, while it does have the help toolbar, isn't the same as the documentation browser. There are clear differences:

• The doc browser disappears and the notebook window appear at a new position on screen


• The notebook window doesn't show "- Wolfram Mathematica 10.0" in the title bar


• When using the search toolbar in the notebook window, it will open a new doc browser instead of showing the results in the same window


• The Back button doesn't work

What I want is to stay within the documentation browser and not open a separate notebook.

---

Cross posted on Wolfram Community

Answer

For notebook to stay in the same place, after Revert action, it needs Saveable -> False option.

Note: A notebook with Saveable -> False cannot be saved using the GUI through File -> Save... It can be saved programmatically using NotebookSave, or exported using Export[..., "NB"], etc.

---

Let's create basic test application with documentation support:

appName = "docNotebookTest";
appPath = FileNameJoin@{$UserBaseDirectory, "Applications", appName};
nbPath = FileNameJoin@{appPath, "Documentation", "English", "altDoc", "test.nb"};

CreateDirectory@DirectoryName@nbPath
Export[FileNameJoin@{appPath, "PacletInfo.m"},
    Paclet[Name -> appName, Version -> "0.0.1",
        Extensions -> {{"Documentation", Language -> "English"}}
    ]
]

Now create simple un-Saveable notebook and restart paclet manager, so that it can find our new documentation notebook:

Export[nbPath,
    Notebook[{Cell["Contents of alternative documentation notebook.", "Text"]},

        Saveable -> False
    ]
]
RestartPacletManager[]

Now if we go to documentation center and search for docNotebookTest/altDoc/test, we'll get our example notebook open in the same window with "HelpViewerToolbar". You can click on reload button and notebook will remain in the same place and it'll retain "HelpViewerToolbar". Close this test documentation notebook for now, so it won't interfere with further tests.

I don't know internals of mechanism behind this, but the fact that toolbar stays there feels a bit accidental. "Ordinary" documentation notebook appears with "HelpViewerToolbar" no matter how you open it e.g.:

NotebookOpen@"paclet:ref/List"

Opens List documentation notebook with "HelpViewerToolbar" on. This is because it uses StyleDefinitions -> FrontEnd`FileName[{"Wolfram"}, "Reference.nb", CharacterEncoding -> "UTF-8"] and Reference.nb style-sheet has:

Cell[StyleData[All, "Working"],
    DockedCells->FEPrivate`FrontEndResource["FEExpressions", "HelpViewerToolbar"]
]

as one of declarations.

If we open our notebook in any other way than searching in documentation center:

nbObj = NotebookOpen@"paclet:docNotebookTest/altDoc/test"

it opens without "HelpViewerToolbar" (if you didn't close test.nb previously opened through documentation center, then above command will just make its window, with toolbar, active).

If we want our notebook to always open with "HelpViewerToolbar", as "ordinary" documentation notebooks do, we should add this toolbar to notebook DockedCells, either directly, or through o style-sheet:

nbObj // NotebookClose
Export[nbPath,
    Notebook[{Cell["Contents of alternative documentation notebook.", "Text"]},
        Saveable -> False,
        DockedCells ->
            FEPrivate`FrontEndResource["FEExpressions", "HelpViewerToolbar"]
    ]
]

Now our notebook always opens with desired toolbar:

nbObj = NotebookOpen@"paclet:docNotebookTest/altDoc/test"

Close notebook and delete our test application:

nbObj // NotebookClose
DeleteDirectory[appPath, DeleteContents -> True]