10
$\begingroup$

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: enter image description here

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?
$\endgroup$
  • 1
    $\begingroup$ paclet: to properly linked can be resolved by using URLParse on them then changing the "Scheme" and "Domain" via ReplacePart and if needed also inserting the path before hitting it with a URLBuild or whatever the functions are again. This assumes you already know where the stuff will be going. Otherwise you'll need relative linking inside the package and to full WRI docs outside. I took that approach at one time before I decided I didn't want to host documentation for my packages (or really deal with documentation in any way...). $\endgroup$ – b3m2a1 Oct 24 at 1:35
  • $\begingroup$ I updated my answer to address the problem with paclet: links. It's in the same spirit as the (slightly later) suggestion by @b3m2a1 above. Could certainly be made a bit more sophisticated, but should be a good start. Does this help, @Chris K? $\endgroup$ – Jan Pöschko Oct 25 at 13:08
8
+200
$\begingroup$

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).

  1. 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.)

$\endgroup$
  • 1
    $\begingroup$ I was experimenting with this too recently, and while the docked cell would be easy to fix, there are many other rendering problems which would be just too much trouble for me to work around. On this page, wolframcloud.com/obj/szhorvat/Published/MaTeX open the Applications heading and see many pink boxes. I was not even able to reproduce these pink boxes if I copied those cells into a new notebook and uploaded that one to the cloud. In the end, I gave up on trying to fix it. $\endgroup$ – Szabolcs Oct 10 at 14:08
  • 1
    $\begingroup$ Trying to share docs like this seems like a lot of work. One would also need to rewrite the links (which now use the paclet:... format). $\endgroup$ – Szabolcs Oct 10 at 14:09
  • 2
    $\begingroup$ However, I do have a package whose documentation is a single notebook (for better or worse). I seriously considered sharing this through the cloud. See here: wolframcloud.com/obj/szhorvat/Published/IGDocumentation Some issues with this: 1. Very slow rendering. This is somewhat understandable because the notebook is huge. But at the time when I originally uploaded it, the rendering was not this slow. Now it takes multiple minutes. $\endgroup$ – Szabolcs Oct 10 at 14:21
  • 1
    $\begingroup$ Generally, for documentation sharing purposes, it would be extremely useful if we could have a way to share strictly read-only, non-interactive notebooks that load fast and don't put a lot of strain on the browser (think e.g. reading them on a Raspberry Pi). It'd be sufficient to have input cells copyable, just like in Mathematica's online documentation. $\endgroup$ – Szabolcs Oct 10 at 14:27
  • 1
    $\begingroup$ @JanPöschko Omitting the fixStyleSheet step also brought the openers back, so something about those StyleSheets. I should be able to figure out the pulldown menus myself. Thanks again for all your help! $\endgroup$ – Chris K Oct 28 at 22:02

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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