update: New & Old base library doc generation

doc/Makefile

@@ -18,7 +18,8 @@ overview-slides.html : overview-slides.md
 	  # # -V maxScale=2
 
 base:
-	mo-doc --source $(MOTOKO_BASE) --output $(OUT)/base --format plain
+	mo-doc --source $(MOTOKO_CORE) --package core --output $(OUT)/core --format plain
+	mo-doc --source $(MOTOKO_BASE) --package base --output $(OUT)/base --format plain
 
 html:
         # TODO: perhaps use node and remark-cli to compile out remark plugins first or use docusaurus to build site properly

doc/docusaurus/docusaurus.config.js

@@ -69,6 +69,12 @@ const config = {
             position: 'left',
             label: 'Base',
           },
+          {
+            type: 'doc',
+            docId: 'core/index',
+            position: 'left',
+            label: 'Core',
+          },
           {
             href: 'https://github.com/dfinity/motoko',
             label: 'GitHub',

doc/docusaurus/static/load_moc.ts

@@ -1,6 +1,7 @@
 import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
 
 const BASE_VERSION = "0.14.8"; /* This may be slightly behind the base files we have locally in nix/sources.json */
+const CORE_VERSION = "0.5.0"; /* This may be slightly behind the base files we have locally in nix/sources.json */
 
 async function addPackage(name, repo, version, dir) {
   const meta_url = `https://data.jsdelivr.com/v1/package/gh/${repo}@${version}/flat`;
@@ -35,6 +36,15 @@ function attachOnRunButton() {
             btns[i].click();
           }
         });
+      addPackage("core", "dfinity/motoko-core", `preview-${CORE_VERSION}`, "src")
+        .then(() => {
+          console.log(`core library version: ${CORE_VERSION}`);
+          // Run code
+          const btns = document.getElementsByClassName("run-button run");
+          for (var i = 0; i < btns.length; i++) {
+            btns[i].click();
+          }
+        });
     });
     document.head.appendChild(script);
   } else {

doc/md/base/Array.md

@@ -1,4 +1,4 @@
-# Array
+# base/Array
 Provides extended utility functions on Arrays.
 
 :::warning

doc/md/base/AssocList.md

@@ -1,4 +1,4 @@
-# AssocList
+# base/AssocList
 Map implemented as a linked-list of key-value pairs ("Associations").
 
 :::note Usage context

doc/md/base/Blob.md

@@ -1,4 +1,4 @@
-# Blob
+# base/Blob
 `Blob` is an immutable, iterable sequence of bytes. Unlike `[Nat8]`, which is less compact (using 4 bytes per logical byte), `Blob` provides a more efficient representation.
 
 Blobs are not indexable and can be empty. To manipulate a `Blob`, convert it to `[var Nat8]` or `Buffer<Nat8>`, perform your changes, then convert it back.

doc/md/base/Bool.md

@@ -1,4 +1,4 @@
-# Bool
+# base/Bool
 Boolean type and operations.
 
 While boolean operators `_ and _` and `_ or _` are short-circuiting,

doc/md/base/Buffer.md

@@ -1,4 +1,4 @@
-# Buffer
+# base/Buffer
 Class `Buffer<X>` provides a mutable list of elements of type `X`.
 It wraps a resizable underlying array and is comparable to `ArrayList` or `Vector` in other languages.
 

doc/md/base/CertifiedData.md

@@ -1,4 +1,4 @@
-# CertifiedData
+# base/CertifiedData
 The Internet Computer allows canister smart contracts to store a small amount of data during
 update method processing so that during query call processing, the canister can obtain
 a certificate about that data.

doc/md/base/Char.md

@@ -1,4 +1,4 @@
-# Char
+# base/Char
 
 ## Type `Char`
 ``` motoko no-repl

doc/md/base/Debug.md

@@ -1,4 +1,4 @@
-# Debug
+# base/Debug
 Utility functions for debugging.
 
 Import from the base library to use this module.

doc/md/base/Deque.md

@@ -1,4 +1,4 @@
-# Deque
+# base/Deque
 Double-ended queue (deque) of a generic element type `T`.
 
 The interface of deques is purely functional, not imperative, and deques are immutable values.

doc/md/base/Error.md

@@ -1,4 +1,4 @@
-# Error
+# base/Error
 Error values and inspection.
 
 The `Error` type is the argument to `throw`, parameter of `catch`.

doc/md/base/ExperimentalCycles.md

@@ -1,4 +1,4 @@
-# ExperimentalCycles
+# base/ExperimentalCycles
 Managing cycles within actors on the Internet Computer (ICP).
 
 The usage of the Internet Computer is measured, and paid for, in _cycles_.

doc/md/base/ExperimentalInternetComputer.md

@@ -1,4 +1,4 @@
-# ExperimentalInternetComputer
+# base/ExperimentalInternetComputer
 Low-level interface to the Internet Computer.
 
 :::warning Experimental API

doc/md/base/ExperimentalStableMemory.md

@@ -1,4 +1,4 @@
-# ExperimentalStableMemory
+# base/ExperimentalStableMemory
 Byte-level access to (virtual) _stable memory_.
 
 :::warning Experimental module

doc/md/base/Float.md

@@ -1,4 +1,4 @@
-# Float
+# base/Float
 Double precision (64-bit) floating-point numbers in IEEE 754 representation.
 
 This module contains common floating-point constants and utility functions.

doc/md/base/Func.md

@@ -1,4 +1,4 @@
-# Func
+# base/Func
 Create functions from simpler inputs, most commonly used when programming in functional style using higher-order functions.
 
 ## Function `compose`

doc/md/base/Hash.md

@@ -1,4 +1,4 @@
-# Hash
+# base/Hash
 
 ## Type `Hash`
 ``` motoko no-repl

doc/md/base/HashMap.md

@@ -1,4 +1,4 @@
-# HashMap
+# base/HashMap
 Class `HashMap<K, V>` provides a hashmap from keys of type `K` to values of type `V`.
 The class is parameterized by the key's equality and hash functions, and an initial capacity.
 However, the underlying allocation occurs only upon the first insertion.

doc/md/base/Heap.md

@@ -1,4 +1,4 @@
-# Heap
+# base/Heap
 Class `Heap<X>` provides a priority queue of elements of type `X`.
 
 The class wraps a purely-functional implementation based on a leftist heap.

doc/md/base/Int.md

@@ -1,4 +1,4 @@
-# Int
+# base/Int
 Signed integer numbers with infinite precision (also called big integers).
 
 :::note

doc/md/base/Int16.md

@@ -1,4 +1,4 @@
-# Int16
+# base/Int16
 Provides utility functions on 16-bit signed integers.
 
 :::note

doc/md/base/Int32.md

@@ -1,4 +1,4 @@
-# Int32
+# base/Int32
 Provides utility functions on 32-bit signed integers.
 
 :::note

doc/md/base/Int64.md

@@ -1,4 +1,4 @@
-# Int64
+# base/Int64
 Provides utility functions on 64-bit signed integers.
 
 :::note

doc/md/base/Int8.md

@@ -1,4 +1,4 @@
-# Int8
+# base/Int8
 Provides utility functions on 8-bit signed integers.
 
 :::info Function form for higher-order use

doc/md/base/Iter.md

@@ -1,4 +1,4 @@
-# Iter
+# base/Iter
 
 ## Type `Iter`
 ``` motoko no-repl

doc/md/base/IterType.md

@@ -1,4 +1,4 @@
-# IterType
+# base/IterType
 
 ## Type `Iter`
 ``` motoko no-repl

doc/md/base/List.md

@@ -1,4 +1,4 @@
-# List
+# base/List
 Purely-functional, singly-linked lists.
 A list of type `List<T>` is either `null` or an optional pair of a value of type `T` and a tail, itself of type `List<T>`.
 

doc/md/base/Nat.md

@@ -1,4 +1,4 @@
-# Nat
+# base/Nat
 Natural numbers with infinite precision.
 
 :::note

doc/md/base/Nat16.md

@@ -1,4 +1,4 @@
-# Nat16
+# base/Nat16
 Provides utility functions on 16-bit unsigned integers.
 
 :::note

doc/md/base/Nat32.md

@@ -1,4 +1,4 @@
-# Nat32
+# base/Nat32
 Provides utility functions on 32-bit unsigned integers.
 
 :::note

doc/md/base/Nat64.md

@@ -1,4 +1,4 @@
-# Nat64
+# base/Nat64
 Provides utility functions on 64-bit unsigned integers.
 
 :::note

doc/md/base/Nat8.md

@@ -1,4 +1,4 @@
-# Nat8
+# base/Nat8
 Provides utility functions on 8-bit unsigned integers.
 
 :::note

doc/md/base/None.md

@@ -1,4 +1,4 @@
-# None
+# base/None
 The `None` type represents a type with _no_ value.
 
 It is often used to type code that fails to return control (e.g. an infinite loop)

doc/md/base/Option.md

@@ -1,4 +1,4 @@
-# Option
+# base/Option
 Optional values can be seen as a typesafe `null`. A value of type `?Int` can
 be constructed with either `null` or `?42`. The simplest way to get at the
 contents of an optional is to use pattern matching:

doc/md/base/Order.md

@@ -1,4 +1,4 @@
-# Order
+# base/Order
 
 ## Type `Order`
 ``` motoko no-repl

doc/md/base/OrderedMap.md

@@ -1,4 +1,4 @@
-# OrderedMap
+# base/OrderedMap
 Stable key-value map implemented as a red-black tree with nodes storing key-value pairs.
 
 A red-black tree is a balanced binary search tree ordered by the keys.

doc/md/base/OrderedSet.md

@@ -1,4 +1,4 @@
-# OrderedSet
+# base/OrderedSet
 Stable ordered set implemented as a red-black tree.
 
 A red-black tree is a balanced binary search tree ordered by the elements.

doc/md/base/Prelude.md

@@ -1,4 +1,4 @@
-# Prelude
+# base/Prelude
 This prelude file proposes standard library features that _may_
 belong in the _language_ (compiler-internal) prelude sometime, after
 some further experience and discussion.  Until then, they live here.

doc/md/base/Principal.md

@@ -1,4 +1,4 @@
-# Principal
+# base/Principal
 Module for interacting with Principals (users, canisters, or other entities).
 
 Principals are used to identify entities that can interact with the Internet

doc/md/base/RBTree.md

@@ -1,4 +1,4 @@
-# RBTree
+# base/RBTree
 Key-value map implemented as a red-black tree (RBTree) with nodes storing key-value pairs.
 
 A red-black tree is a balanced binary search tree ordered by the keys.

doc/md/base/Random.md

@@ -1,4 +1,4 @@
-# Random
+# base/Random
 A module for obtaining randomness on the Internet Computer (IC).
 
 This module provides the fundamentals for user abstractions to build on.

doc/md/base/Region.md

@@ -1,4 +1,4 @@
-# Region
+# base/Region
 Byte-level access to isolated, (virtual) stable memory _regions_.
 
 This is a moderately lightweight abstraction over IC _stable memory_ and supports persisting

doc/md/base/Result.md

@@ -1,4 +1,4 @@
-# Result
+# base/Result
 Error handling with the `Result` type.
 
 ## Type `Result`

doc/md/base/Stack.md

@@ -1,4 +1,4 @@
-# Stack
+# base/Stack
 Class `Stack<X>` provides a minimal LIFO stack of elements of type `X`.
 
 See library `Deque` for mixed LIFO/FIFO behavior.

doc/md/base/Text.md

@@ -1,4 +1,4 @@
-# Text
+# base/Text
 Utility functions for `Text` values.
 
 A `Text` value represents human-readable text as a sequence of characters of type `Char`.

doc/md/base/Time.md

@@ -1,4 +1,4 @@
-# Time
+# base/Time
 System time
 
 ## Type `Time`

doc/md/base/Timer.md

@@ -1,4 +1,4 @@
-# Timer
+# base/Timer
 Timers for one-off or periodic tasks. Applicable as part of the default mechanism.
 
 :::note Timer resolution

doc/md/base/Trie.md

@@ -1,4 +1,4 @@
-# Trie
+# base/Trie
 Functional key-value hash map.
 
 Provides an applicative (purely functional) hash map, called a *trie*, where each operation returns a new version of the structure without mutating the original.

doc/md/base/TrieMap.md

@@ -1,4 +1,4 @@
-# TrieMap
+# base/TrieMap
 Class `TrieMap<K, V>` provides a map from keys of type `K` to values of type `V`.
 The class wraps and manipulates an underlying hash trie, found in the `Trie` module.
 The trie is a binary tree where element positions are determined using the hash of the keys.

doc/md/base/TrieSet.md

@@ -1,4 +1,4 @@
-# TrieSet
+# base/TrieSet
 
 Sets are partial maps from element type to unit type,
 i.e., the partial map represents the set with its domain.

doc/md/base/index.md

@@ -1,4 +1,4 @@
-# Index
+# Index of package base
 
 * [Array](Array.md) Provides extended utility functions on Arrays.
 * [AssocList](AssocList.md) Map implemented as a linked-list of key-value pairs ("Associations").