Sync v12 core docs (#991)

* WIP sync stdlib docs (Js does not work for now)

* rename core to stdlib for >= v12

* fix doc generation for v12

* fix version selector for core/stdlib

* add missing react keys

* update stdlib.json

* remove unused flag

* fix selector for non core/stdlib modules

* revert gendocs.res since it'll be moved to rescript monorepo

* fix iterator docstrings

Author: tsnobip

data/api/v12.0.0/belt.json

@@ -1,14 +1,20 @@
 # Overview
 
-## ReScript Core
+## Stdlib
 
-[Core](api/core) is ReScript's new standard library. It replaces the complete `Js` module as well as some of the more frequently used modules from `Belt` and is recommended to use with uncurried mode.
+[Stdlib](api/stdlib) is ReScript's new standard library. It replaces the complete `Js` module as well as some of the more frequently used modules from `Belt` and is recommended to use with uncurried mode.
 
-In ReScript 11, it is shipped as a separate npm package `@rescript/core` that is added to your project as per the [installation instructions](/docs/manual/next/installation). In future ReScript versions, it will be included with the `rescript` npm package itself.
+In ReScript 11, it was shipped as a separate npm package `@rescript/core`.
+
+Since Rescript 12, it is now included with the `rescript` npm package itself.
 
 ## Additional Libraries
 
 ReScript ships with these two additional modules in its standard library:
 
-- [Belt](api/belt): immutable collections and extra helpers not available in [Core](api/core).
-- [Dom](api/dom): Dom related types and modules. Contains our standardized types used by various userland DOM bindings.
+- [Belt](api/belt): immutable collections and extra helpers not available in JavaScript / [Stdlib](api/stdlib).
+- [Dom](api/dom): Dom related types and modules. Contains our standardized types used by various userland DOM bindings.
+
+## Legacy Modules
+
+The [Js](api/js) module is superseded by [Stdlib](api/stdlib).

data/api/v12.0.0/js.json

@@ -62,7 +62,7 @@ module RightSidebar = {
         }
         let title = `${Option.isSome(deprecatedIcon) ? "Deprecated " : ""}` ++ name
         let result =
-          <li className="my-3">
+          <li className="my-3" key={href}>
             <a
               title
               className="flex items-center w-full font-normal text-14 text-gray-40 leading-tight hover:text-gray-80"
@@ -125,12 +125,12 @@ module SidebarTree = {
       switch hasChildren {
       | true =>
         let open_ =
-          node.path->Array.join("/") ===
+          href ===
             moduleRoute
             ->Array.slice(~start=0, ~end=Array.length(moduleRoute) - 1)
             ->Array.join("/")
 
-        <details key={node.name} open_>
+        <details key={href} open_>
           <summary className={summaryClassName ++ classNameActive}>
             <Next.Link className={"inline-block w-10/12"} href>
               {node.name->React.string}
@@ -148,7 +148,7 @@ module SidebarTree = {
           }}
         </details>
       | false =>
-        <li className={"list-none mt-1 leading-4"}>
+        <li className={"list-none mt-1 leading-4"} key={href}>
           <summary className={summaryClassName ++ classNameActive}>
             <Next.Link className={"block"} href> {node.name->React.string} </Next.Link>
           </summary>
@@ -172,6 +172,15 @@ module SidebarTree = {
             ReactEvent.Form.preventDefault(evt)
             let version = (evt->ReactEvent.Form.target)["value"]
             let url = Url.parse(router.asPath)
+            switch url.pagepath[1] {
+            | Some("core") | Some("stdlib") =>
+              if version < "v12.0.0" {
+                url.pagepath[1] = "core"
+              } else {
+                url.pagepath[1] = "stdlib"
+              }
+            | _ => ()
+            }
 
             let targetUrl =
               "/" ++
@@ -184,9 +193,10 @@ module SidebarTree = {
           <VersionSelect
             onChange
             version
-            availableVersions=Constants.coreVersions
+            availableVersions=Constants.stdlibVersions
             nextVersion=?Constants.nextVersion
           />
+
         | None => React.null
         }}
       </div>
@@ -309,21 +319,21 @@ let default = (props: props) => {
         | Value({name, signature, docstrings, deprecated}) =>
           let code = String.replaceRegExp(signature, /\\n/g, "\n")
           let slugPrefix = "value-" ++ name
-          <>
+          <React.Fragment key={slugPrefix}>
             <H2 id=slugPrefix> {name->React.string} </H2>
             <DeprecatedMessage deprecated />
             <CodeExample code lang="rescript" />
             <DocstringsStylize docstrings slugPrefix />
-          </>
+          </React.Fragment>
         | Type({name, signature, docstrings, deprecated}) =>
           let code = String.replaceRegExp(signature, /\\n/g, "\n")
           let slugPrefix = "type-" ++ name
-          <>
+          <React.Fragment key={slugPrefix}>
             <H2 id=slugPrefix> {name->React.string} </H2>
             <DeprecatedMessage deprecated />
             <CodeExample code lang="rescript" />
             <DocstringsStylize docstrings slugPrefix />
-          </>
+          </React.Fragment>
         }
       })
 

data/api/v12.0.0/core.json renamed to data/api/v12.0.0/stdlib.json

@@ -35,6 +35,7 @@ module Buffer = {
 }
 
 module ChildProcess = {
+  type options = {maxBuffer?: float}
   @module("child_process")
-  external execSync: string => Buffer.t = "execSync"
+  external execSync: (string, ~options: options=?) => Buffer.t = "execSync"
 }

data/api/v12.0.0/toc_tree.json

@@ -25,7 +25,8 @@ let nextVersion =
     ? None
     : Some(versions.next, versions.next->Semver.tryGetMajorString)
 
-let coreVersions = [latestVersion]
+let stdlibVersions =
+  versions.latest === "v11.0.0" ? [latestVersion] : [("v11.0.0", "v11"), latestVersion]
 
 let allReactVersions = [("latest", "v0.12.0"), ("v0.11.0", "v0.11.0"), ("v0.10.0", "v0.10.0")]
 

pages/docs/manual/v12.0.0/api.mdx

@@ -26,7 +26,10 @@ let make = (
       <>
         <SectionHeader value=Constants.dropdownLabelNext />
         <option className="py-4" key=value value> {React.string(label)} </option>
-        <SectionHeader value=Constants.dropdownLabelReleased />
+        {switch availableVersions {
+        | [] => React.null
+        | _ => <SectionHeader value=Constants.dropdownLabelReleased />
+        }}
       </>
     }}
     {React.array(children)}

src/ApiDocs.res

@@ -5,7 +5,11 @@ let makeCategories: string => array<Sidebar.Category.t> = version => [
     name: "",
     items: [
       {name: "Overview", href: `/docs/manual/${version}/api`},
-      {name: "Core", href: `/docs/manual/${version}/api/core`},
+      if version >= "v12.0.0" {
+        {name: "Stdlib", href: `/docs/manual/${version}/api/stdlib`}
+      } else {
+        {name: "Core", href: `/docs/manual/${version}/api/core`}
+      },
     ],
   },
   {