---
tags: drafts
---

# OCaml Documentation Architecture (draft)

**Authors:** Anil Madhavapeddy, Jon Ludlam (contributions welcome, just leave comments or contact us)

This document covers the various technologies in the OCaml Platform to handle the needs of documenting and learning about OCaml programming.

| Name | Interactive | Graphical |
| -------- | -------- | -------- |
| IDE | Y | Y |
| CLI | Y | N |
| Notebook | Y | Y |
| Books | N | N |
| Webpages | N | Y |
| Playground | Y | Y |

digraph G {
  layout=circo;
  IDE [shape="box", fontsize=30.0 style=filled color=green];
  Browser [shape="box", fontsize=30.0 style=filled,color=green];
  Notebook [shape="box", fontsize=30.0 style=filled,color=green];
  CLI [shape="box",fontsize=30.0 style=filled,color=green];
  SourceCode [shape="box",fontsize=30.0 style=filled,color=green];
  Books [shape="box",fontsize=30.0 style=filled,color=green];
  Screencasts -> IDE;
  Tutorials -> Browser;
  Tutorials -> IDE;
  Tutorials -> CLI;
  LibraryDocs -> Browser;
  LibraryDocs -> IDE;
  LibraryDocs -> CLI;
  LibraryDocs -> Notebook;
  Manpages -> CLI;
  Articles -> Browser;
  Papers -> Books;
  Papers -> Notebook;
  Benchmarks -> Browser;
  Benchmarks -> Notebook;
  Videos -> Browser;
  MOOCs -> Browser;
  MOOCs -> Notebook;
  MOOCs -> IDE;
  MOOCs -> Books;
  MOOCs -> CLI;
  Lectures -> Notebook;
  Lectures -> Books;
  Lectures -> Browser;
  Playgrounds -> Notebook;
  Jupyter -> Notebook;
  DistroManager -> CLI;
  DistroManager -> Browser;
  LibraryAuthor -> IDE;
  LibraryAuthor -> Browser;
  LibraryAuthor -> CLI;
}

Archtypes:
- Beginner
- LibraryAuthor
- AppDeveloper
- DistroManager

Styles:
- tutorials
- library docs
- manpages
- articles
- papers
- benchmarks
- videos / talks
- moocs
- lecture notes
- interactive playgrounds
- jupyter
- screencasts
- podcasts
- twitch
- README.md
- release notes

Access mechanisms:
- IDE (VSCode/Emacs/Vim)
- search function for libraries/types
- Web Browser
- search function for libraries/types/examples
- odoc search via elastic/lucene but needs ranking to be useful ("hoogle")
- craigs operator search and "weird ocaml syntax"
- an indexable manual for syntax
- Notebook (Jupyter)
- CLI (Utop)
- Books
- Snippets
- spin
- drom
- dune init
- other templating?

Authoring technologies:
- mld/odoc
- jupyter notebooks
- latex for papers
- markdown:
- mdx
- blog markdown
- github markdown
- rst (e.g. dune docs)
- explore workflows
- ofronds

Feedback mechanisms:
- Forums (discuss.ocaml.org)
- GH Issues
- Wiki with live code in it (tutorials)
- Discord/IRC/Matrix/Slack
- Link to projects using this

# docs.ocaml.org

[](https://hackmd.io/ezdoqt3aSRWz6mB1JcvE7w)

The various `voodoo` components deal with building "docs.ocaml.org" ("doo").

## Cluster Workflow

This works on multiple universes.

graph LR
    subgraph building
    ocluster -- prep --> S3
    end
    subgraph solving
    opam-repo --> versions -- submit --> ocluster
    end
    subgraph docgen
    S3 -- make --> odocl
    odocl --> HTML --> Website
    odocl --> LaTeX --> PDF
    odocl --> manpages
    end

There are three phases to generating documentations. Each of them is separately parallelisable, but there are further opportunities to improve this in the linking phase in the future.

- **Solving:** an opam-repository git hash is solved to give an exact list of package dependencies for each version of each package.
- **Compiling:** we then need to build `.cmt[i]` files for each artefact and upload that to an S3 bucket. This is done through [ocluster](https://github.com/ocurrent/ocluster)
- **Linking:** The artefacts are all downloaded and then turned into linked `odocl` files using `voodoo-link` There is one `odocl` per page or module and these are all then converted into the website or PDF.

## Local opam Workflow

Install odoc/odocl/html files as opam packages installed

when building with dune, dune can add `-I` to the path of the opam installed odoc files to generate docs - and it can generate HTML files that link to the opam-installed html files. Adding a new option to odoc to give the base URL of a particular root page will allow the local docs to link to the package-wide docs.

## Local monorepo Workflow

Figure out how to get the compiler cmtis into odoc files, then:

dune build @doc

### Updating

After finding a solution for each version of each package, this should be stored. For each new commit to opam-repository we should check the solution still works.

After each release of a compiler, we should resolve for the
latest version of each package, so the 'current' version of
each package is linked to the latest possible versions of its dependent packages. Doing this at compiler-release time seems a reasonable cadence, though we could do it more often if we have enough space.

For everything we've ever solved, we should produce corresponding HTML for that universe, so links can be permanent (thus we should limit the number of solutions we come up with!)

### Caching

By storing the cmti/odoc/odocl files in directories that are
named by the hash of the dependencies, the odoc files should be essentially perfectly reproducible, so we can cache at the odoc-file level.

# Progress

Initial version available [here](http://hub2.cl.cam.ac.uk/packages)