Workbench (Eclipse version) HTML Documentation Build HTML issues

Description

The HTML generated for local viewing by Workbench (Eclipse plugin version 10.1.757) has some issues before they can be published. This post is in continuation of the original question about HTML Build

Issues

2. Some images are missing
3. It is not possible to copy code from the webpage
4. The content of the collapsed content is empty
• In collapsed pages the expressions are not rendered but shown as Click code to copy
5. Quicklinks on the top right corner have an incorrect path
• I tremble with excitement.... – QuantumDot Dec 22 '16 at 16:16
• @QuantumDot You no longer have to wait, enjoy the ride ;') – Frank Martin Dec 23 '16 at 16:27

Update 10-2017: I noticed that they released an update of these tools, so some of these steps are outdated. I adjusted this answer to the newest release of Workbench 10.1.822. It has become somewhat easier, therefore I also created an automated script for my usecase. Feel free to use it:

(* Directory containing html folder, e.g. C:/project/build/projectname-HTML/html *)
$htmlDirectory = "path/to/html/folder"; (*1.1 Copy Dependencies to Main Folder*) localFiles = FileNameJoin[{$htmlDirectory,"standard"}]
folders = FileNames["*",localFiles]
CopyDirectory[#,
FileNameJoin[{$htmlDirectory,Last[FileNameSplit[#]]}]]&/@folders; (*1.2 Fix HTML Links and Scripts*) htmlFiles = FileNames["*.html",{ FileNameJoin[{$htmlDirectory,"ref"}],
FileNameJoin[{$htmlDirectory,"guide"}], FileNameJoin[{$htmlDirectory,"tutorial"}]
}]

Do[
Block[{source},
source = Import[file,"Source"];

(* Insert jQuery *)
source = StringReplace[source,
"<script src=\"/webMathematica/Resources/Documentation/English/javascript/reference.js\"></script>"->
"
<script src=\"../javascript/jquery/core/1.7.2/jquery.min.js\"></script>
<script src=\"../javascript/reference.js\"></script>
"
];

(* fix relative paths *)
source = StringReplace[source, {
"/webMathematica/Resources/Documentation/English/"->"../",
"/2013/javascript/"->"../javascript/"
}];

(* fix bullet.gif *)
source = StringReplace[source,"../images/mathematicaImages/bullet.gif"->"../images/bullet-greysq.gif"];

(* save *)
Export[file,source,"Text"];
],{file,htmlFiles}]

cssFontFile = FileNameJoin[{$htmlDirectory,"css","fonts.css"}] css = Import[cssFontFile,"Text"]; css = StringReplace[css,"/fonts/sourcesanspro/v8/fonts/"->"/fonts/sourcesanspro/v8/"]; Export[cssFontFile,css,"Text"] (*3. Fix Missing Content in Collapsed Containers*) fasterPageLoadFile = FileNameJoin[{$htmlDirectory,"javascript","faster-page-load.js"}]
js = StringReplace[js,"baselang.slice(0,-3)"->"baselang"];

(*4. Fix Click to Copy Cells*)
subpagesFile = FileNameJoin[{$htmlDirectory,"javascript","sub-pages.js"}]; subpagesFile//FileExistsQ DeleteFile[subpagesFile] Export[subpagesFile, Uncompress["1:eJzdVstu2zAQzLWH/gNrGCCFtopdtDn0cUp7yClAc0yDghZXJlFaEkTKThH437uUrFgPylCawC1CWJBN7c5yZ4YyXy3S71cvXp6cTJlIo2IFiQ3CHLj4zUhcJJFVacICcvdjNn9HcEwZDS+Sc9CaqNWSBiHwSDJfpBsqZlNmpTJBqAyj14Jb/tbk0Q0NOpFVNMHwjUpEugnCjRJWIuBncjabeaLdWPOcIBz5Quoy3Nqc0boODT4NpW0GklZca2zLZFpZRgkNrmc3gyByNMjcD+JaxnWG2DPcXsaM/nw/+0Bd00MtVyJUJbM8zRh1fb5xNKBumeYRoERZssS5Eq38HviJ6IOVrGPqZmyCBLWUFjOkP2PbndwS0AaOpedCLR+rZg9iQMsBVfxLfhDr4xlvsX3/Y1sF4jU/PSWmWLhPPTNlkxBuM56Iq/LBRZJATvhubhKEkVbRr/0Wh50xXa67AJcFa3xvfIWYF9qyfbEKfrd2nmOM6RS7LCzkroZUWmAAWrd6DIK699AqXcO55gZfHlIJ6OjfxmYtmCjVmmcGHgDDhegH1X3kYIs8ITFH894/aBA7RGO9jn9KpLezMSxWGEfisGPQAx49tk2ftVOPb9Zn4tcGkyCIPPsYq9zYSRO0nKE9h/Msg0QQJQyx6c7vBGH21icGSuIbW4D2NzxpktY+iangzidI9b+mhDsdIMq324yS10QdVs9TmXagTDXbxyqPgJSHKXZcpkluWox3jNWsPyRiO/YAL0NWGgEwYlfWCFuvNajX8o9UzPyNYIOa/TeiPYVuTyId3v4ABBnUIw=="],"Text"] (*5. Fix Code Copying from Web Page*) clipboardJs = FileNameJoin[{$htmlDirectory,"javascript","clipboard.en.js"}];
clipboardJsNew = FileNameJoin[{$htmlDirectory,"javascript","clipboard.js"}]; RenameFile[clipboardJs,clipboardJsNew] clipboardCss = FileNameJoin[{$htmlDirectory,"css","clipboard.css"}]
css = Import[clipboardCss,"Text"];
css = StringReplace[css,"/webMathematica/Resources/Documentation/English/images/"->"../images/"];
Export[clipboardCss,css,"Text"]


All the fixes below are post-build, it would be better to modify the DocumentationTools so that we don't have to do these steps each time we want to generate the HTML (although keep in mind that these files might be overwritten in case of an update). Also, the steps below should be the same in case of a Windows machine.

1. Incorrect script and link paths

If you have managed to build the HTML the first thing you encounter that the HTML files are missing their dependencies as we only see plain HTML, see image 1.

1.1 Dependency Locations

The build did store these dependencies in the build folder, just not in the location that the HTML-file specifies. There are two folders which you can use: the html/standard and html/minimal folder. I recommend using the html/standard folder as you will be able to adjust the files to your needs. I recommend pasting all contents of html/standard to html/.

1.2 Inspect/Fix Paths in the HTML-file

If we open a HTML file we see that the link and script-tag path do not point towards this folder, see image 2. We also note that the jquery script is not referenced at all so we need to add jquery before the other script tags, see figure 4.

1.3 Examine

Now, if we open the HTML-files, it looks somewhat like the documentation pages we are used to. Also you should be able to open and collapse sections (even though its content might be absent), see figure 5.

2 Fix Missing CSS fonts

If we inspect the HTML with the developer tools -and look in the console- we see a bunch of errors regarding missing fonts, see image 6.

2.1 Font Locations

The fonts that are missing are in the build folder, but somehow the path is again incorrect. The fonts that are missing are located in: /html/fonts/sourcesanspro/v8/SourceSansPro-Regular.ttf

To fix this we adjust the html/css/fonts.css, with the following replacement: replace /fonts/sourcesanspro/v8/fonts/ with /fonts/sourcesanspro/v8/, see figure 7.

3 Fix Missing Content in Collapsed Containers

When you try to expand a collapsed item, e.g. the scope section, no content is shown. And with the DeveloperTools the following error is dispatched, see figure 8.

The links do not exist, they seem to have cut the filename. For this you need to edit file /html/standard/javascript/faster-page-load.js. In which you need to remove .slice(0,-3) from line 2, see figure 9.

Note: if you are looking at the webpages on your local machine, make sure you use chrome and using the flag "--allow-file-access-from-files"

4 Fix Click to Copy Cells

Sometimes, not exactly sure when, the input cells show Click to Copy instead of their actual input, the Click to Copy should be the alternate text if no image can be found. This also fixes the problem when the collapsed pages do not open at all. To fix this you will need to update the files /html/javascript/sub-pages.js, I copied them from the Wolfram site itself.

Note: In previous versions of the DocumentationTools you also needed to add image-swap.js to the javascript folder, download it from here wolfram site itself.

5 Fix Code Copying from Web Page

It would be nice if you can copy code from the website and paste it directly into Mathematica just as the official Mathematica site. A few things need to be updated.

Note: In previous versions of Documentation Tools you needed to update the jQuery version, this is no longer needed

5.1 Rename clipboard.en.js to clipboard.js

You need to rename /html/javascript/clipboard.en.js to /html/javascript/clipboard.js. (Assuming you want the english version, and no multi-language support).

Add the following line to your HTML files: <link rel="stylesheet" href="../css/clipboard.css" />
Replace the following in html/css/clipboard.css: replace /webMathematica/Resources/Documentation/English/images/ with ../images/.
Note: In previous versions of DocumentationTools you had to download the two images image1 and image2 and store them in html/images/
• One font fix to add: a new version of "reference-special-styles" needs to be downloaded – b3m2a1 Aug 19 '17 at 20:56