Tracking: Website plans

[ELLIOTTCABLE]

Well, I guess we need a website.

• It'd be nice to provide a quick, skim-friendly tutorial for using melange alongside (or instead of, as appropriate) other ecosystem tools: "Documentation for testing existing projects on Melange", Documentation for testing existing projects on Melange #106
• A logo or mascot! A logo, mascot, or other representation for the project #135

No specific issue opened — someone make one:

• A web playground
• PPXes can run in a single executable with ppxlib (Allow using PPXes as libraries  #171)

[anmonteiro]

Brain dump from Discord:

I think in rough order of priority, we should document:

1. FFI / bs.deriving interop, and other stuff (including advanced) I might be forgetting – should probably have lots of references to the OCaml manual
2. playground!
3. landing page with installation instructions (bc we already have the README)

the playground is probably somewhat challenging, and something I can dedicate my time to.

Contributions are very much appreciated for other stuff.

In the meantime, I revived the old website here: https://bucklescript.vercel.app/, which should be a good starting point.

even though it probably takes more work, it'd be great to build the docs website at https://melange.re/ with Melange itself, so we can make sure we're dogfooding the project.

[anmonteiro]

Add to the docs:

• generators Enable generators by default (even in dependencies) #117
• virtual library support Virtual libs support #56 / Allow implementation and interface files to live in different dirs #76

[jchavarri]

• Explain how current integration with Dune works. I know from experience one might get too excited and start trying to use (library ..) stanzas and such 😄 One comment with questions about dune: Remove theme + init subcommands #124 (comment).

[martindemello]

if melange can consume rescript-generated libraries in a single pipeline (i.e. having just one build invocation that will run rescript over the rescript source then run melange and generate javascript that imports the rescript-generated library) that would be a great thing to document

[bentxt]

In lack of better idea how to approach this, I would like to offer my help to start a website here. I think we could start with something simple and then iterate from there.
Personally I like to take a few markdown files as source for static html files. I then prefer to simply upload them via (s)ftp, but I know others use github pages or a cdn.
Anyway I would like to help, tell/show how.

[kennetpostigo]

I'm willing to contribute some time working on the website for melange :)

[jchavarri]

I have been exploring https://github.com/dmbaturin/soupault. It was recommended on Discord and the ideas behind it looked interesting.

Quick summary: it's a static site generation tool influenced by Unix philosophy and quite easily plugged into any kind of setup, as it operates on html elements. One way to define it would be a "Like jQuery, but written in OCaml, well integrated with command line, and running at build time".

To test Soupault and see if it could be a good fit, I put up a small skeleton site that does the following:

• Converts markdown files to html with omd
• Generates tables of contents and nav links automatically (based on ocamlbook.org)
• Make sure OCaml code snippets compile with ocamlc (we can call bsc at some point when it supports stdin, and also inject the resulting js too)
• Convert OCaml snippets to reason syntax with refmt and inject them into resulting html
• Highlight code at build time with prism.js

All that is done with less than 20 source files in the project. It looks promising, but this setup might become too complex if we want to integrate things like React, Next.js etc.

In general, I'm not convinced as this approach makes "dogfooding" a bit harder. Also it can be a barrier for contributors.

What do you all think?

Source: https://github.com/jchavarri/melange-docs
Site: https://jchavarri.github.io/melange-docs/

[jfrolich]

Looks great @jchavarri. I am exploring an Odoc fork that is able to pick up markdown files in the repository. This can also be a possible option for documentation generation. It has some of the advantages of your approach and some other advantages:

• We can cross-reference between markdown and API docs (I wrote a PR to OMD to convert markdown to ocamldoc)
• We have a single tool that incorporates free form docs like "Getting started" and the API documentation
• It's relatively easy to switch between Reason/OCaml syntax as that is build-in to Odoc (not sure about code fences though).
• Jordwalke did some work to generate Paradoc documentation with Odoc, perhaps we can adopt the paradoc HTML templates?

I am still hacking on it and might run into some roadblocks so not sure if it's a viable option for now. But let me know what you think about this approach!

An interesting aspect is, that with melange we can render pages both statically and hydrate them in JavaScript using React. There is still some work necessary to make this work, especially in writing a React-ppx that works with my native static renderer, and is API compatible with the React-ppx in melange. It's more of a stretch goal, but it would surely show the capabilities of melange.

[jchavarri]

Better integration with markdown would be great to have in odoc @jfrolich 👍 thank you for your work on that.

It's relatively easy to switch between Reason/OCaml syntax as that is build-in to Odoc

Last time I checked odoc —for the jsoo-react docs— I ran into this problem where syntax in odoc seems to be a top level setting. I mean that either one exports all docs with OCaml syntax or with Reason syntax. And there is no awareness of this setting in "in-docs snippets" which are handled just like text. But I wanted to have "dual" output to later allow users to switch syntax without reloading the page for better experience. Is this possible in some way?

For completion, another approach I've seen other projects use is run "standard" odoc first, and then run soupault after it to add enhancements in a small postprocessing step (example in Dream makefile). But if markdown files were added with this approach we'd lose cross-reference as you mention.

Jordwalke did some work to generate Paradoc documentation with Odoc, perhaps we can adopt the paradoc HTML templates?

This project looks great. I specially like the one-file packing and offline search mode —although it has the obvious counter side of increased bundle sizes. I will take a closer look 👀 thanks for sharing!

---

Edit: here's the branch where I attempted to add a "dual syntax" output to odoc: https://github.com/ocaml/odoc/compare/master...jchavarri:generator_both?expand=1. As mentioned, it only affected signatures, but could not find out how to include snippets in documentation comments as well.

[jfrolich]

Last time I checked odoc —for the jsoo-react docs— I ran into this problem where syntax in odoc seems to be a top level setting. I mean that either one exports all docs with OCaml syntax or with Reason syntax. And there is no awareness of this setting in "in-docs snippets" which are handled just like text. But I wanted to have "dual" output to later allow users to switch syntax without reloading the page for better experience. Is this possible in some way?

Yes that is true, but the capability is there to generate both, so storing both in the HTML should just be a matter of adapting the data model and store both (that's why I am forking).

About the code blocks. Perhaps we can make a specially annotated codeblocks that are always in the source language of the file itself, and will be parsed to different syntaxes by odoc?

For completion, another approach I've seen other projects use is run "standard" odoc first, and then run soupault after it to add enhancements in a small postprocessing step (example in Dream makefile).

Yeah I saw projects do this as well. It's mostly just a hack, would be great to have a proper solution for this.

But if markdown files were added with this approach we'd lose cross-reference as you mention.

I don't think we necessarily loose that (the markdown files are just translated to ocamldoc).

This project looks great. I specially like the one-file packing and offline search mode —although it has the obvious counter side of increased bundle sizes. I will take a closer look 👀 thanks for sharing!

I probably first try to generate into this layout and not necessarily the one file packing. (although it would be nice if we could generate the one-file packing for portability).

[jchavarri]

I don't think we necessarily loose that (the markdown files are just translated to ocamldoc).

I meant with an "off-the-hook" approach with odoc + separate md files -> process html with soupalt :)

[jchavarri]

Managed to thread OCaml code snippets through melange bsc in the soupault experiment site, so JS output can be generated automatically. An example can be seen at https://jchavarri.github.io/melange-docs/dune/. Next step should be to process js code to add syntax highlighting as well.

gif

[kennetpostigo]

@jchavarri FWIW, not sure what the target audience for the site is, but I dread the previous, top, next setup.

[ghost]

Bystander comment. My ideal static site (assuming unbundled development is too bleeding edge) would use bucklescript-tea, simple routing, manually configure the code splitting, remark js, and tailwind for the homepage, general content pages. Do the initial mockups in webflow, then use tailwind to implement the designs.

[jchavarri]

I dread the previous, top, next setup

Yes, I'm not a fan either 😄 Right now I'm prototyping and experimenting, and open to ideas and help to build a decent 1st version without having to create a whole design system or stuff like that, as the whole thing will most likely be thrown away at some point. I am currently checking https://pmarsceill.github.io/just-the-docs/ which looks much nicer than the typesettings.css template I was using before. I have adapted it to Soupault to get index / side bar generated automatically. There are still some things to fix, but a preview can be seen at the same url: https://jchavarri.github.io/melange-docs/

use bucklescript-tea, simple routing, manually configure the code splitting, remark js

How would something like auto-generation of translated Reason code + bsc JavaScript output work with such a setup? I agree there are upsides of using Melange with bs-tea or next.js or anything else for the docs site from a dogfooding perspective, but I can't see an easy way to do markdown or html processing.

I might be too insisting on having a nice automated pipeline to transform OCaml snippets to get Reason and JS code, but it's probable that the site will end up having a lot of them. For an example, I took the interop page from the original BuckleScript doc site and adapted to remove all re and js snippets, and entitled sentences. Here's the updated source and rendered page.

[jchavarri]

Added a page with goals and history: https://jchavarri.github.io/melange-docs/intro/
Here's the PR in case you want to comment (the html can be ignored, it is generated from md) jchavarri/melange-docs#1 :)

[jchavarri]

There is quite some work to create the docs. As some folks have expressed interest in helping, if you think the approach in the repo linked above is good enough for v1, here are some self-contained tasks where any help is welcome:

Content

• "Editor support" section (maybe could be under "Installation"), pointing to vscode-ocaml-platform and any other editors available.
• Complete installation.md page, to cover esy and nix, and mention opam package not being available yet (but maybe can be pinned?).
• Add a new section for Standard Library. It should point to both OCaml and ReScript documentation and maybe explain bundle size consequences. As inspiration, there's a similar BuckleScript section.
• There was a section "Differences from native OCaml" in BS docs, it might be interesting to adapt it as well.
• There could be a new section (maybe "Interop with OCaml"?) about using OCaml libraries. BS docs also had a section related: "Use existing OCaml libraries".
• Replace links to reasonml.github.io and bucklescript.github.io docs to OCaml org (or better, to the compiler API docs that might be available in multi-syntax for Melange :)
• Add a section "Production users of Melange"

If none of the above is appealing, there could be a new Guides section that explains how to set up a project with Webpack or Esbuild for example, use a ppx library...

UI

• Fix code tabs which are very ugly now, the code is in this plugin.
• Add "Edit this page" links at the bottom, it should probably be a Soupault plugin as it relies on page information that is only available at build time.

---

Edit: in progress

• I will be working on the "Build system" section: Dune, bsconfig.json, etc. If you have questions, or want to pick any of the things above, please share here so there's no duplication of work :) I assume nobody has previous experience with Soupault, the setup should be straightforward but if you run into issues, please lmk as well.
• Migrate Interop docs. There's already an index page and Cheatsheet page. I think we can take as base the markdown sources that existed in original BS repo and remove anything that is not purely technical descriptions. To migrate one .md file from BS repo:
  • remove all ```reason and ```js blocks
  • add a header with nav_order attribute (see example)

[ghost]

auto-generation of translated Reason code + bsc JavaScript output work with such a setup?

I can research this a bit. I am sure there is a solution for generic markdown to html rendering. I assume you are specifically asking about invoking compiler logic to perform conversions, in the browser, as well as some general integration with code highlighting?

[jfrolich]

Love your work @jchavarri! I also made a bit more progress on odoc. How about I work backwards, trying to generate the current docs (including this layout) with my odoc fork (with the same markdown files), so that we can easily add-in API docs.

This might take a while to get right so until that time we can do some magic with Soupault.

[jfrolich]

I can research this a bit. I am sure there is a solution for generic markdown to html rendering. I assume you are specifically asking about invoking compiler logic to perform conversions, in the browser, as well as some general integration with code highlighting?

I think doing this in the browser would create an enormous dependency. We can generate them when compiling the docs. Basically trying if it parses, and if so print the reason or rescript syntax as alternative code blocks.

[jchavarri]

Sounds good @jfrolich ! I am looking into migrating the articles in the "Interop" section articles to the docs, and there are a lot of links to API modules like Js.Dict and such that for the time being will remain unlinked. So I think it'll be great to have an odoc-based solution at some point. I am not sure we'll be able to replace all Soupault functionality in odoc (e.g. processing of in-doc code snippets).

[jchavarri]

There is now a website in melange.re, and playground in https://melange.re/v1.0.0/playground (or https://melange.re/unstable/playground if you want to use the bleeding edge) 🎉 .

Improvements, additions or bugs can be reported either in this repo or in https://github.com/melange-re/melange-re.github.io.