[ANN] Bogue tutorials 0.1.0

Hi, I’m pleased to announce an ongoing series of tutorials for Bogue (the Desktop GUI library for OCaml):

So far only three are written:

More will come when time permits!

Each tutorial includes code that can either be pasted onto a toplevel, or automatically executed (the executables are shipped in the ocaml-tutorials opam package.

Feedback appreciated! (hopefully constructive :wink: )

18 Likes

This kind of soft documentation is greatly appreciated, TYSM!
The tutorials appear fine on the central docs bogue-tutorials 0.1.0 (latest) · OCaml Package, but the images don’t display there unfortunately. Have we figured out how to embed stuff like images? I’m not sure myself.

Until something like package assets are standardized in odoc I don’t think that we’ll have images showing up there. For now I’ve been following the odoc-assets directory pattern that gets my docs to work with odig at least.

indeed, last time I asked here it was not possible. For these tutorials I did a small hack to copy the images into the odoc dir, but I don’t know how to tell the ‘central docs’ to run this (make images)

By the way, where can I find out how the ‘central doc’ at ocaml.org/p/… is generated?

I gave a talk on the general ideas here, and the you can see the source on github of the pipeline and the driver. If you want to help with the assets, it’s the driver that’ll need updating - I don’t think odoc itself will need changes, or at the very least they’ll be small bugfixes. We’ve got plans to work on it pretty soon, but if anyone else wants to jump in and help we’d be very happy to see it! @sabine is probably the right person to ping.

4 Likes

The ocamldoc language needs to be extended to denote asset reference/insertions. I don’t think it’s a good idea to rely on raw html (we can then check for the existence of assets during rendering which is good for doc QA).

1 Like

You’re right of course, I was focussing on what’s required for the assets to appear on the ocaml.org website. In fact we do have image syntax on the horizon, and we could well check for the existence of the assets during compilation/linking once we’ve got that.

I’m happy to announce 2 more tutorials:

Layouts : a tree structure
Widgets and connections : a graph structure

The latter even has a small reversi-like game where all squares are actually widgets talking to each other, demonstrating the use of “connections”.
reversi

6 Likes