Putting package documentation on Wolfram Cloud

Question

So, I've finally released v1.0 of my EcoEvo package. Yay. Maybe I'll give an overview here soon.

I'd also like to advertise to my colleagues, perhaps non-Mathematica users, who might use it. The documentation, made with Workbench, has some worked examples already, so I thought it might be easiest to publish them on the Wolfram Cloud. I opened one such tutorial in the Mathematica help browser and hit "Publish to Cloud...", and it doesn't look too bad!

However, it doesn't look perfect either:

The search bar was included and is totally non-functional. The links under "Related Tutorials" at the top and bottom don't work.

Still, this seems 95% of the way towards having decent-looking documentation on the web without much trouble.

Questions:

1. Is there a way to remove that broken search-bar header and fix the links?
2. Can I upload all the documentation pages to the cloud automatically, and maintain the directory structure?

Answer 1

Good to hear it (almost) works!

1. The header is a docked cell, so, to remove it, you could evaluate

SetOptions[EvaluationNotebook[], DockedCells->{}]

in the notebook (before you publish it to the cloud).

2. To upload a whole directory to the cloud, you can use

CopyDirectory["localpath", CloudObject["cloudpath"]]

(with localpath and cloudpath set appropriately). To make all the created cloud objects public, you could temporarily change $Permissions, or you could (recursively) iterate over them using CloudObjects and apply SetPermissions to each of them. We're working on more direct ways to do this, also in the GUI ("Publish Directory to Cloud"). Documentation also needs to be further improved, but the guide page about Managing Content in the Cloud is a good starting point for more information.

To address the problem with paclet: hyperlinks: I think the best option (for now) is to preprocess each notebook before publishing it to the cloud, replacing the target URLs of all such ButtonBoxes with corresponding cloud object URLs. Here's some code that does this:

dirPrefixes = <|
   "Guides" -> "guide", {"ReferencePages", "Symbols"} -> "ref", 
   "Tutorials" -> "tutorial"|>;

subdirString[prefix_String] := prefix
subdirString[prefixes_List] := FileNameJoin[prefixes]

pacletLinkQ[str_String] := StringStartsQ[str, "paclet:"]
pacletLinkQ[_] := False

fixPacletLink[str_, pacletName_, targetURL_] := 
 StringReplace[
   str, (StartOfString ~~ "paclet:" ~~ pacletName) -> targetURL] <> 
  ".nb"

fixPacletLinks[nb_Notebook, pacletName_, targetDir_String] := 
 nb /. ButtonBox[content_, opts1___, ButtonData -> data_?pacletLinkQ, 
    opts2___] :> 
   ButtonBox[content, 
    ButtonFunction :> (FrontEndExecute[
        NotebookLocate[{URL[#2], None}]] &), opts1, 
    ButtonData -> fixPacletLink[data, pacletName, targetDir], opts2]

removeDockedCells[
  Notebook[content_, opts1___, DockedCells -> _, opts2___]] := 
 Notebook[content, opts1, DockedCells -> {}, opts2]
removeDockedCells[Notebook[content_, opts___]] := 
 Notebook[content, DockedCells -> {}, opts]

resetMagnification[
  Notebook[content_, opts1___, (Rule | RuleDelayed)[Magnification, _],
    opts2___]] := Notebook[content, opts1, opts2]
resetMagnification[nb_Notebook] := nb

fixStyleSheet[
  Notebook[content_, opts1___, StyleDefinitions -> _, opts2___]] := 
 Notebook[content, opts1, 
  StyleDefinitions -> FrontEnd`FileName[{"Wolfram"}, "Reference.nb"], 
  opts2]

publishDocNB[filename_String, target : CloudObject[targetURL_, ___], 
  prefix_, pacletName_] := 
 Module[{nb, newNB, obj}, nb = Get[filename]; 
  newNB = resetMagnification@
    fixStyleSheet@
     removeDockedCells@fixPacletLinks[nb, pacletName, targetURL]; 
  obj = FileNameJoin[{target, prefix, FileNameTake[filename]}]; 
  Print["Publishing ", filename, " to ", obj]; 
  CloudPublish[newNB, obj]]

publishDocDir[pacletDir_, subdir_, prefix_, target_] := 
 Module[{nbfiles = 
    FileNames["*.nb", 
     FileNameJoin[{pacletDir, "Documentation", "English", 
       subdirString[subdir]}]], pacletName = FileNameTake[pacletDir]},
   publishDocNB[#, target, prefix, pacletName] & /@ nbfiles]

PublishPacletDocs[pacletDir_String, target_CloudObject] := 
 KeyValueMap[publishDocDir[pacletDir, #1, #2, target] &, dirPrefixes]

Calling the function like

PublishPacletDocs["~/Projects/EcoEvo/EcoEvo", CloudObject["EcoEvo"]]

will publish all documentation notebooks in the given paclet directory (assuming they're all in the usual subdirectory structure of Documentation/English) to a cloud directory EcoEvo in your cloud home directory.

This also takes care of points 1 and 2, and, as a little bonus, I also made it change the stylesheet to Wolfram/Reference.nb (since Wolfram/FunctionPageStyles.nb doesn't exist right now) and reset the Magnification to 1. (You could also deploy a custom stylesheet to the cloud and reference that.)

You can see the result here: https://www.wolframcloud.com/obj/jpoeschko/EcoEvo/guide/EcoEvo.nb

(Hope it's okay that I took your https://github.com/cklausme/EcoEvo and published it to my own Wolfram Cloud account for now. Just let me know if I should replace the link in this answer with a link to your own published version.)