Initial support for oranda (#183)

This PR switches our developer facing documentation over to oranda.

.gitignore

@@ -2,3 +2,4 @@
 **/gerbers/*
 *-bak
 **/target/*
+public/

README.md

@@ -2,13 +2,6 @@
 
 This repository is for the MnemOS Operating System.
 
-## Stable Docs
-
-Currently, MnemOS is being rewritten as part of the v0.2 version. The current source may not
-match the currently published documentation!
-
-[hosted mnemOS v0.1 documentation](https://mnemos.jamesmunns.com)
-
 ## Development and API Docs
 
 `rustdoc` output for the current `main` branch can be built locally with `cargo doc --open`.

oranda-workspace.json

@@ -0,0 +1,66 @@
+{
+  "build": {
+    "static_dir": "assets"
+  },
+  "workspace": {
+    "name": "MnemOS",
+    "members": [
+      {
+        "slug": "MnemosProjectOverview",
+        "path": "."
+      },
+      {
+        "slug": "kernel",
+        "path": "./source/kernel"
+      },
+      {
+        "slug": "melpomene",
+        "path": "platforms/melpomene"
+      },
+      {
+        "slug": "pomelo",
+        "path": "platforms/pomelo"
+      },
+      {
+        "slug": "allwinner-core",
+        "path": "platforms/allwinner-d1/core"
+      },
+      {
+        "slug": "crowtty",
+        "path": "tools/crowtty"
+      },
+      {
+        "slug": "alloc",
+        "path": "source/alloc"
+      },
+      {
+        "slug": "forth3",
+        "path": "source/forth3"
+      },
+      {
+        "slug": "abi",
+        "path": "source/abi"
+      },
+      {
+        "slug": "spitebuf",
+        "path": "source/spitebuf"
+      },
+      {
+        "slug": "sermux-proto",
+        "path": "source/sermux-proto"
+      },
+      {
+        "slug": "trace-proto",
+        "path": "source/trace-proto"
+      },
+      {
+        "slug": "beepy",
+        "path": "platforms/beepy"
+      },
+      {
+        "slug": "f3repl",
+        "path": "tools/f3repl"
+      }
+    ]
+  }
+}

oranda.json

@@ -0,0 +1,7 @@
+{
+    "project": {
+        "name": "Mnemos Project Overview",
+        "description": "This page provides an overview of the entire MnemOS project. The other boxes on this page provide an overview of the individual crates that make up MnemOS.",
+        "readme_path": "./README.md"
+    }
+}

platforms/allwinner-d1/core/Cargo.toml

@@ -2,6 +2,10 @@
 name = "mnemos-d1-core"
 version = "0.1.0"
 edition = "2021"
+description = """
+A hardware abstraction library for the Allwinner D1, targeted
+at use in the mnemos operating system.
+"""
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -29,4 +33,4 @@ default-features = false
 
 [dependencies.riscv]
 version = "0.10"
-features =[ "critical-section-single-hart"]
+features =[ "critical-section-single-hart"]

platforms/allwinner-d1/core/README.md

@@ -0,0 +1,4 @@
+# Allwinner D1 Core
+
+A hardware abstraction library for the Allwinner D1, targeted
+at use in the mnemos operating system.

platforms/allwinner-d1/core/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

platforms/beepy/Cargo.toml

@@ -2,6 +2,9 @@
 name = "mnemos-beepy"
 version = "0.1.0"
 edition = "2021"
+description = """
+Hardware support specific to the SQFMI Beepy development board
+"""
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -29,4 +32,4 @@ features = ["async-await"]
 default-features = false
 
 [dependencies.mycelium-bitfield]
-version = "0.1.2"
+version = "0.1.2"

platforms/beepy/README.md

@@ -0,0 +1,3 @@
+# Beepy
+
+Hardware support specific to the SQFMI Beepy development board

platforms/beepy/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

platforms/melpomene/Cargo.toml

@@ -2,6 +2,10 @@
 name = "melpomene"
 version = "0.1.0"
 edition = "2021"
+description = """
+A desktop simulator, suitable for experimenting with MnemOS without
+any external hardware requirements.
+"""
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

platforms/melpomene/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

platforms/pomelo/Cargo.toml

@@ -2,6 +2,10 @@
 name = "pomelo"
 version = "0.1.0"
 edition = "2021"
+description = """
+Pomelo is a browser-based simulator for MnemOS, compiled as
+a WASM binary.
+"""
 
 [dependencies]
 chrono = { version = "0.4.26", features = ["wasmbind"] }

scripts/install-ci-deps.sh

@@ -8,6 +8,8 @@ mkdir -p ./target
 # Install docs deps
 rustup toolchain install stable
 
-# Install mdbook deps
-curl -L https://github.com/rust-lang/mdBook/releases/download/v0.4.17/mdbook-v0.4.17-x86_64-unknown-linux-gnu.tar.gz | tar xvz
-mv ./mdbook ./target
+# Install Oranda
+# TODO: switch to curlbash once they release a prerelease binary!
+cargo install oranda -f \
+    --git https://github.com/axodotdev/oranda \
+    --rev ec4b0b8360b0adc1aa5240e213bf275b262670e2

scripts/run-ci-build.sh

@@ -14,10 +14,8 @@ rm -rf ./target/ci-publish || :
 mkdir -p ./target/ci-publish/
 cp -r ./target/doc ./target/ci-publish/
 
-# note: --dest-dir is relative from the book.toml
-./target/mdbook \
-    build \
-    --dest-dir ./../target/ci-publish/book \
-    ./book
+# Build with oranda
+oranda build
 
-cp ./assets/index.html ./target/ci-publish
+# Copy to publish directory
+cp -r ./public/* ./target/ci-publish

source/abi/Cargo.toml

@@ -1,8 +1,9 @@
 [package]
 name = "mnemos-abi"
 version = "0.1.0"
-description = "A tiny embedded operating system common library"
-repository = "https://github.com/jamesmunns/pellegrino"
+description = """
+Data structures and definitions shared between the kernel and userspace.
+"""
 authors = ["James Munns <james@onevariable.com>"]
 edition = "2021"
 readme = "./README.md"

source/abi/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

source/alloc/Cargo.toml

@@ -1,5 +1,9 @@
 [package]
 name = "mnemos-alloc"
+description = """
+An async allocator wrapper. This crate provides collection types and helper functions to allow
+for async handling of allocations, including turning allocation async.
+"""
 version = "0.1.0"
 edition = "2021"
 

source/alloc/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

source/forth3/Cargo.toml

@@ -2,6 +2,11 @@
 name = "forth3"
 version = "0.1.0"
 edition = "2021"
+description = """
+forth3 is a forth-inspired scripting language runtime. It can be used
+on targets without an allocator, and supports native builtins written
+in Rust, either as async or blocking functions.
+"""
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

source/forth3/README.md

@@ -0,0 +1,9 @@
+# forth3
+
+forth3 is a forth-inspired scripting language runtime. It can be used on targets without an allocator, and supports native builtins written in Rust, either as async or blocking functions.
+
+## Development Documentation
+
+Please see [the development docs](https://mnemos-dev.jamesmunns.com/doc/forth3/index.html) for documentation of the current `main` branch.
+
+Docs can be built locally with `cargo doc`.

source/forth3/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

source/kernel/Cargo.toml

@@ -1,9 +1,14 @@
 [package]
 name = "mnemos"
 version = "0.1.0"
-description = "A tiny embedded operating system kernel"
-repository = "https://github.com/jamesmunns/pellegrino"
-authors = ["James Munns <james@onevariable.com>"]
+description = """
+The MnemOS Kernel. Built around asynchronous kernel tasks which use
+message passing as the primary means of interaction. Provided as a
+no_std library crate.
+"""
+authors = [
+    "James Munns <james@onevariable.com>",
+]
 edition = "2021"
 readme = "./README.md"
 

source/kernel/README.md

@@ -1,6 +1,12 @@
 # MnemOS Kernel
 
-This is the kernel for the MnemOS general purpose operating system.
+The MnemOS Kernel. Built around asynchronous kernel tasks which use message passing as the primary means of interaction. Provided as a `no_std` library crate.
+
+## Development Documentation
+
+Please see [the development docs](https://mnemos-dev.jamesmunns.com/doc/kernel/index.html) for documentation of the current `main` branch.
+
+Docs can be built locally with `cargo doc`.
 
 ## License
 

source/kernel/oranda.json

@@ -0,0 +1,8 @@
+{
+  "project": {
+    "name": "kernel"
+  },
+  "components": {
+    "mdbook": false
+  }
+}

source/mstd/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

source/sermux-proto/Cargo.toml

@@ -2,6 +2,11 @@
 name = "sermux-proto"
 version = "0.1.0"
 edition = "2021"
+description = """
+Wire types used by the `SerialMuxService` in the mnemos kernel. Extracted as a
+separate crate to allow external decoders (like `crowtty`) to share protocol
+definitions
+"""
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -15,4 +20,4 @@ default-features = false
 use-std = []
 
 [dev-dependencies.proptest]
-version = "1.2"
+version = "1.2"

source/sermux-proto/README.md

@@ -0,0 +1,9 @@
+# Sermux Protocol
+
+Wire types used by the `SerialMuxService` in the mnemos kernel. Extracted as a separate crate to allow external decoders (like `crowtty`) to share protocol definitions
+
+## Development Documentation
+
+Please see [the development docs](https://mnemos-dev.jamesmunns.com/doc/sermux-proto/index.html) for documentation of the current `main` branch.
+
+Docs can be built locally with `cargo doc`.

source/sermux-proto/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

source/spitebuf/Cargo.toml

@@ -2,6 +2,11 @@
 name = "spitebuf"
 version = "0.1.0"
 edition = "2021"
+description = """
+Spitebuf is an async MPSC queue, based on the Vyukov algorithm
+originally implemented in the heapless crate. It can be used on
+targets with or without an allocator.
+"""
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

source/spitebuf/README.md

@@ -0,0 +1,9 @@
+# Spitebuf
+
+Spitebuf is an async MPSC queue, based on the Vyukov algorithm originally implemented in the heapless crate. It can be used on targets with or without an allocator.
+
+## Development Documentation
+
+Please see [the development docs](https://mnemos-dev.jamesmunns.com/doc/spitebuf/index.html) for documentation of the current `main` branch.
+
+Docs can be built locally with `cargo doc`.

source/spitebuf/oranda.json

@@ -0,0 +1,5 @@
+{
+  "components": {
+    "mdbook": false
+  }
+}

source/trace-proto/Cargo.toml

@@ -2,6 +2,11 @@
 name = "mnemos-trace-proto"
 version = "0.1.0"
 edition = "2021"
+description = """
+Wire types used by the binary tracing subscriber used on hardware targets.
+Extracted as a separate crate to allow external decoders (like `crowtty`)
+to share protocol definitions.
+"""
 
 [features]
 std = ["tracing-serde-structured/std", "serde/std"]

source/trace-proto/README.md

@@ -0,0 +1,9 @@
+# Trace Protocol
+
+Wire types used by the binary tracing subscriber used on hardware targets. Extracted as a separate crate to allow external decoders (like `crowtty`) to share protocol definitions.
+
+## Development Documentation
+
+Please see [the development docs](https://mnemos-dev.jamesmunns.com/doc/trace-proto/index.html) for documentation of the current `main` branch.
+
+Docs can be built locally with `cargo doc`.