Repository files navigation

This repository contains the source for Melange public documentation site.

If you are looking for Melange source instead, it can be found inhttps://github.com/melange-re/melange.

Warning At the moment, this is awork in progress, opened to thepublic. The content and technology used to build the website are beingdeveloped and the website itself is not hosted yet on its final domain.

After cloning the repository, install the necessary JavaScript packages:

yarn

Then runmake dev from the folder where the repository lives.

Optionally, to fetch the melange odoc documentation and generate markdown into docs/api, you will need the melange package installed into your switch and run:

make pull-melange-docs SYNTAX="re"make pull-melange-docs SYNTAX="ml"

Optionally, to run some of the tools to auto-generate parts of thedocumentation, you will need an opam switch with the required dependencies. Toset it up, run:

make init

All code snippets should be written in OCaml syntax. A development-time scriptis available to automatically generate Reason syntax snippets from the OCamlones. Before running this script, you will need to set up an opam switch.Instructions can be found in the"Tooling for docsgeneration" section.

To run the script:

dune build @re

To promote any changes to the originalmd file, one can run:

dune build @re --auto-promote

Publishing is done automatically from GitHub actions:

• Every commit tomaster will publish in theunstable folder, i.e.https://melange.re/unstable
• Every tag pushed with thev* format will publish to a folder with the samename as the tag. For example, the branch with tagv4.0.0 will publish tohttps://melange.re/v4.0.0/.

When a new version ofmelange is published in opam, a new release of the docsand playground should be published. The process is as follows:

• Updatedocumentation-site.opam to pointmelange andmelange-playgroundpackages to the commit of the new release (they need to be pinned so that theMelange docs can be accessed on a stable path)
• Update versions of the compiler listed in the playground (app.jsx)
• In the docs markdown pages, grep for the last version of Melange that was usedand replace it with the newer one.
• Open a PR with the changes above
• After merging the PR, create a new branchx.x.x-patches. This branch will beused to publish any patches or improvements to that version of the docs /playground
• In that branch, add a new command on the mainMakefile to publish a new tag,e.g.

.PHONY: move-vx.x.x-tagmove-vx.x.x-tag:## Moves the vx.x.x tag to the latest commit, useful to publish the vx docsgit push origin :refs/tags/vx.x.xgit tag -fa vx.x.xgit push origin --tags

• Call the newly created command to create a new version selectable from thewebsite:make move-vx.x.x-tag
• Update the navigation bar indocs/.vitepress/config.mts, underthemeConfig.nav setting, so that the first item is the one of the newversion, andunstable is shown last
• Once the new version is published, we need to make sure other versions remainSEO friendly:
  • Inmaster: updateadd_canonical to point to the newvx.x.x, so thattheunstable version of the docs starts referring to that version as thecanonical one. To do so:
    • update the version inadd_canonical.ml
    • rundune test --auto-promote
  • Iny.y.y-patches: updateadd_canonical in versiony.y.y that was lastbefore, to point tovx.x.x as well. To do so:
    • update the version inadd_canonical.ml
    • rundune test --auto-promote
    • uncomment the relevant code inpublish-version.yml
• In thegh-pages branch:
  • replace the default version with the new oneinindex.html
  • updaterobots.txt to point to the new version sitemap

After making changes in themaster branch, you may want some or all of thosechanges to appear in the latest stable version's docs. As an example, let's saythat the latest stable version is 4.0.0. Then you should:

1. Checkout branch4.0.0-patches
2. Cherry pick the commits you want to add
3. Push your changes to the branch
4. Runmake move-v4.0.0-tag to publish the branch tohttps://melange.re/v4.0.0/