Reorganize docs (oxcaml#3935)

This reorganizes the docs for easy deployment to the oxcaml website

Author: ccasin

jane/doc/README.md

@@ -0,0 +1,11 @@
+# Documentation of Jane Street OCaml extensions
+
+This directory contains documentation of our extensions.
+
+The `extensions/` subdirectory is the source code for the OxCaml website,
+mirrored to the web on compiler release. Internal links there will not work on
+Github. Adding new files in the existing directories should just work, but if
+you change the structure it is also necessary to change the website's code,
+which is kept in an internal Jane Street repository.
+
+CR ccasinghino: Automate the necessary changes.

jane/doc/extensions/stack/intro.md renamed to jane/doc/extensions/_01-stack-allocation/intro.md

@@ -1,6 +1,13 @@
+---
+layout: documentation-page
+collectionName: Stack allocation
+title: Intro
+---
+
 # Introduction to Stack Allocations
 
-See also the full feature [reference](reference.md) and [common pitfalls](pitfalls.md).
+See also the full feature [reference](../reference) and
+[common pitfalls](../pitfalls).
 
 This page describes how OCaml sometimes allocates values on a stack,
 as opposed to its usual behavior of allocating on the heap.
@@ -162,4 +169,4 @@ over which values are stack-allocated, including:
     heap-allocated (and may freely escape regions), even though the record
     itself may be stack-allocated.
 
-For more details, read [the reference](./reference.md).
+For more details, read [the reference](../reference).

jane/doc/extensions/stack/pitfalls.md renamed to jane/doc/extensions/_01-stack-allocation/pitfalls.md

@@ -1,3 +1,8 @@
+---
+layout: documentation-page
+collectionName: Stack allocation
+title: Pitfalls
+---
 # Some Pitfalls of Stack Allocations
 
 This document outlines some common pitfalls that may come up when
@@ -6,15 +11,16 @@ suggested workarounds. Over time, this list may grow (as experience
 discovers new things that go wrong) or shrink (as we deploy new
 compiler versions that ameliorate some issues).
 
-If you want an introduction to stack allocations, see the [introduction](intro.md).
+If you want an introduction to stack allocations, see the
+[introduction](../intro).
 
 ## Tail calls
 
 Many OCaml functions just happen to end in a tail call, even those
 that are not intentionally tail-recursive. To preserve the
 constant-space property of tail calls, the compiler applies special
 rules around locality in tail calls (see [the
-reference](./reference.md)).
+reference](../reference)).
 
 If this causes a problem for calls that just happen to be in tail
 position, the easiest workaround is to prevent them from being

jane/doc/extensions/stack/reference.md renamed to jane/doc/extensions/_01-stack-allocation/reference.md

@@ -1,8 +1,13 @@
+---
+layout: documentation-page
+collectionName: Stack allocation
+title: Reference
+---
 # Stack Allocations Reference
 
 The goal of this document is to be a reasonably complete reference to stack
 allocations in OCaml. For a gentler introduction, see [the
-introduction](intro.md).
+introduction](../intro).
 
 The stack allocations language extension allows the compiler to
 stack-allocate some values, placing them on a stack rather than the

jane/doc/extensions/unboxed-types/index.md renamed to jane/doc/extensions/_02-unboxed-types/intro.md

@@ -1,17 +1,17 @@
-# Unboxed types (implemented)
+---
+layout: documentation-page
+collectionName: Unboxed types
+title: Intro
+---
 
-[unboxed types proposal]: ../../proposals/unboxed-types/index.md
-[kind annotation]: ../../proposals/unboxed-types/syntax.md#kind-annotations
+The "unboxed types" extension provides users with additional control over the
+way their data is represented in memory and registers. These new types have
+different {\em layouts}, which is part of their [kind](../kinds/intro), to
+distinguish them from normal OCaml types.
 
-This page documents the fragment of the [unboxed types
-proposal][] that is implemented. Watch this page
-for updates on what's available.
-
-This page is intended to be a brief overview; the details are in the [unboxed types
-proposal][].
-
-**Warning:** This is all early days for unboxed types. Expect plenty of papercuts. That
-said, we have confidence that these features are safe to use. Annoying, but safe.
+This page gives a comprehensive overview of the extension.  Unboxed types are
+still in active development, with new features being added frequently, and the
+documentation here is kept up to date.
 
 # Layouts
 
@@ -109,10 +109,10 @@ let f5 x = (x : (_ : immediate))
 let f6: type (a: bits32). a -> a = fun x -> x
 ```
 
-Reference [the relevant section of the design proposal][kind annotation] for the full syntax.
-The complete annotation design is not yet implemented and the syntax should be read
-with `kind ::= layout-name` for now. It also provides reasoning around some design
-decisions and contains additional examples.
+The full syntax can be found in the [documentation for kinds](../kinds/syntax).
+The complete annotation design is not yet implemented and the syntax should be
+read with `kind ::= layout-name` for now. It also provides reasoning around some
+design decisions and contains additional examples.
 
 
 ## Layouts in module inclusion
@@ -186,7 +186,7 @@ modules in the `janestreet_shims` library.)
 ## Unboxed options
 
 We now have `type 'a or_null : value_or_null`, the type of unboxed options.
-It has constructors `Null` and `This v`. See the [`or_null` document](null.md)
+It has constructors `Null` and `This v`. See the [`or_null` document](../or-null)
 for more details.
 
 # Unboxed products

jane/doc/extensions/unboxed-types/null.md renamed to jane/doc/extensions/_02-unboxed-types/or-null.md

@@ -1,10 +1,16 @@
+---
+layout: documentation-page
+collectionName: Unboxed types
+title: Or null
+---
+
 # Adding null to types
 
 This document describes the way we can add a null value to types, thus granting a
 non-allocating version of `option`. This extension builds on the *layouts*
-system described in the [main document for unboxed types](index.md). Before
+system described in the [main document for unboxed types](../intro). Before
 reading this document, you may wish to read up through the
-[layouts](index.md#layouts) section of the main document.
+[layouts](../intro#layouts) section of the main document.
 
 # Adding null
 

jane/doc/extensions/parallelism/intro.md renamed to jane/doc/extensions/_03-parallelism/intro.md

@@ -1,8 +1,14 @@
+---
+layout: documentation-page
+collectionName: Parallelism
+title: Intro
+---
+
 # Introduction to Parallelism
 
 OCaml 5 introduces multicore, which allows parallel execution in a single process.
 Based on that, the OCaml Language team developed a collection of compiler features and libraries:
-- Extending the [mode system](../modes/intro.md) to track values' concurrent
+- Extending the [mode system](../modes/intro) to track values' concurrent
   usages, so they can be used concurrently safely.
 - Higher-level parallelism primitives to allow users to fully expose
   opportunities of parallelism in their programs, without worrying low-level

jane/doc/extensions/_04-modes/intro.md

@@ -0,0 +1,15 @@
+---
+layout: documentation-page
+collectionName: Modes
+title: Intro
+---
+
+# Introduction to the Mode System
+
+The locality mode used for [Stack allocation](../stack/intro) has been
+extended to more axes, each tracking a property of values, in order to support
+features such as [Parallelism](../parallelism/intro) and
+[Uniqueness](../uniqueness/intro). This documentation gives a general
+introduction to the mode system.
+
+*This is a stub. Documentation will come soon.*

jane/doc/extensions/modes/reference.md renamed to jane/doc/extensions/_04-modes/reference.md

@@ -1,12 +1,18 @@
+---
+layout: documentation-page
+collectionName: Modes
+title: Reference
+---
+
 The goal of this document is to be a reasonably complete reference to the mode system in
 OCaml.
 
-<!-- CR zqian: For a gentler introduction, see [the introduction](intro.md). -->
+<!-- CR zqian: For a gentler introduction, see [the introduction](../intro). -->
 
 The mode system in the compiler tracks various properties of values, so that certain
 performance-enhancing operations can be performed safely. For example:
-- Locality tracks escaping. See [the local allocations reference](../stack/reference.md)
-- Uniqueness and linearity tracks aliasing. See [the uniqueness reference](../uniqueness/reference.md)
+- Locality tracks escaping. See [the local allocations reference](../stack/reference)
+- Uniqueness and linearity tracks aliasing. See [the uniqueness reference](../uniqueness/reference)
 - Portability and contention tracks inter-thread sharing.
     <!-- CR zqian: reference for portability and contention -->
 

jane/doc/extensions/modes/syntax.md renamed to jane/doc/extensions/_04-modes/syntax.md

@@ -1,3 +1,9 @@
+---
+layout: documentation-page
+collectionName: Modes
+title: Syntax
+---
+
 # Modes and modalities
 Currently a mode expression is simply a space-delimited list of modes.