Need built in docs when not internet connected

[whaleygeek]

The online docs are taking good shape, but when you're on the road with no internet access, online docs are a real pain, because you can't get to them. For example, the train ride from London to Cambridge has lots of 'notspots' where I can't get mobile connectivity at all.

It would be good to have the docs embedded inside Mu with a HELP button in Mu, so that the latest html docs for that version of Mu are bundled with it, and pressing HELP opens a locally bundled copy of the docs. This would give users everything they need to code, offline. As it is, I have to separately cache the docs, and go through the pain of working out what version of docs goes with what version of the editor and trying to keep them in step.

It also means that on a (usually offline) Raspberry Pi, you have everything you need in front of you. Generally schools don't allow Raspberry Pi's onto their internet because the wifi key is stored in plaintext on the pi, and this leaks the wifi key which schools don't want the kids to use.

[ntoll]

Exactly. I intend to make "help" local web pages based on the MicroPython content. When you click the help button your OS's default browser will open to an appropriate page on your local FS. ;-)

Great minds think alike (or fools seldom differ). 😄

[carlosperate]

We could embed the html documentation into the 1-file executables, however this would then cause the the browser to point to an "ugly" temporary location created every time the program is executed (and additional code to be added just to locate this temporary folder, which depends on PyInstaller not changing their implementation again in the future).

Alternatively, we could copy the executable with the html documentation folder and any another other data/information and zip it up for distribution. This could be "cleaner" presentation to the user, but we would then lose the "everything in just one file" wrapper.

[whaleygeek]

Or you could embed the html as a bundle inside the exe, and unzip it to a folder in the users documents folder on first use (or in the application data, wherever that is on the various platforms - there are API's you can call I think to get both the user home directory and also an application data directory).

[alistair-broomhead]

@whaleygeek's suggestion strikes me as a reasonable one, but we need to make sure the documentation is for the same version as you have installed. This is workable if we include a version number or hash in the documentation directory when extracted so we can tell whether the documentation needs to be updated. Alternatively including this version number or hash in the directory structure would allow side-by-side documentation for multiple versions of mu, but I'm not sure what the use-case for this would be, and it would leave mess that the average user is not going to clear up after themselves.

[alistair-broomhead]

The other option is to write the docs as a SPA, which is opened in a QtWebView within mu

[carlosperate]

If a webview widget is added to Mu (not quite sure if @ntoll was playing with the concept of having it side by side with the editor, or taking a new tab), then we can use that as a way to display the help documentation, which would have the added benefit of packing it inside the application bundle, so the documentation and software are always synchronised.

[ntoll]

OK... related to this discussion is the following PR: #98

This is ONLINE only for the time being. This is better than nothing and I expect we'll want to move to offline soon as per the discussion.

[ZanderBrown]

If the blocks branch is merged this should definitely be considered as Mu would already be using WebKit

[ntoll]

FYI... updated docs / website / help here: https://codewith.mu/

[carlosperate]

In future releases, is the aim still to include the offline docs with the Mu installers?

[ntoll]

That's an option, but I think it may be better (to keep the size of the installer down) to zip them up and include them as a file in the GitHub release. In fact, that feels like the right solution.

[carlosperate]

Ah! Didn't think of that, sounds like a really good alternative, good idea!

[devdanzin]

Revisiting this to report on some explorations of the "zip docs" options, focusing on browsers at first.

The current full https://codewith.mu/ docs zip to about 22MB and can't be navigated as-is on the file system, due to (simple) Jekyll routing and absolute URLs.

I didn't succeed in configuring Jekyll to reliably generate files for local serverless browsing. It's easy to get close by using relative paths. This would allow for the simplest "implementation": just pop up a browser pointing to a local file.

Instead of hacking the hrefs to work on disk, we could serve the docs locally. Works with SimpleHTTPServer if we slightly patch the source to allow building with .html (and index.html) appended to the right places. Maybe patching a local server to use the same (very simple) routing instead could also work. Likely to break under random firewall and anti-virus shenanigans.

Regarding size, if we optimize the PNGs and encode the GIFs as MP4 files (changing <img> to <video autoplay loop muted playsinline> ), we can reduce the zipped size to about 7MB.