Move back to using mdBook for documantation

mdBook seems somewhat simpler and more lightweight than Docusaurus, so I’m thinking it might just be good to go with it for now! It also has support for [preprocessors](https://rust-lang.github.io/mdBook/for_developers/preprocessors.html) which could be handy if we want to generated some sort of hyperlinked language specification.
pikelet-lang · Oct 17, 2020 · 15c3c0f · 15c3c0f
1 parent 7498d2d
commit 15c3c0f
Show file tree

Hide file tree

Showing 69 changed files with 5,777 additions and 11,373 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -93,14 +93,33 @@ jobs:
           command: clippy
           args: -- -D warnings
 
-  website:
+  book:
     runs-on: ubuntu-latest
-    name: Build website
+    name: Build and Test Book
+    env:
+      MDBOOK_VERSION: '0.4.2'
+      MDBOOK_LINKCHECK_VERSION: '0.7.0'
     steps:
       - uses: actions/checkout@v2
-      - name: Install website dependencies
+      - name: Install mdBook
+        # Install prebuilt binaries where possible to improve CI performance
+        run: |
+          mkdir -p $HOME/mdbook
+          curl -L https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_VERSION/mdbook-v$MDBOOK_VERSION-x86_64-unknown-linux-gnu.tar.gz | tar xz -C $HOME/mdbook
+          echo "::add-path::${HOME}/mdbook/"
+          mkdir -p $HOME/mdbook-linkcheck
+          curl -L https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/v$MDBOOK_LINKCHECK_VERSION/mdbook-linkcheck-v$MDBOOK_LINKCHECK_VERSION-x86_64-unknown-linux-gnu.tar.gz | tar xz -C $HOME/mdbook-linkcheck
+          echo "::add-path::${HOME}/mdbook-linkcheck/"
+      - name: Install Javascript dependencies
         run: yarn install
-        working-directory: ./website
-      - name: Build website
+        working-directory: book
+      - name: Build additional Javascript
         run: yarn build
-        working-directory: ./website
+        working-directory: book
+      - name: Build book
+        run: mdbook build
+        working-directory: book
+      - name: Test book
+        run: mdbook test
+        working-directory: book
+      # TODO: Deploy to Github Pages on crate release
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,7 @@
+# Rust
 /target/
 **/*.rs.bk
 Cargo.lock
+
+# Yarn
+/node_modules
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,3 +1,61 @@
-# Contributing to Pikelet
+# Contributing
 
-A guide to contributing to Pikelet [can be found in the documentation](/website/docs/pikelet/contributing.md).
+## Code of Conduct
+
+Please note that this project is released with a [Code of Conduct](./CODE_OF_CONDUCT.md).
+By participating in this project you agree to abide by its terms.
+
+[code_of_conduct]: https://github.com/pikelet-lang/pikelet/blob/master/CODE_OF_CONDUCT.md
+
+## Matrix room
+
+Joining the matrix room at [#pikelet:matrix.org][pikelet-matrix] is a good way to get in touch with the developers and community.
+
+[pikelet-matrix]: https://app.element.io/#/room/#pikelet:matrix.org
+
+## Prerequisites
+
+We use [Rust][rust] as our implementation language, which can be installed using the [rustup] tool.
+
+For the best experience in working with Rust we also recommend installing IDE support for your editor of choice:
+
+- [Rust Analyzer][rust-analyzer] (for VS Code, Vim Emacs, etc.)
+- [IntelliJ Rust][intellij-rust] (for IntelliJ-based IDEs)
+
+You can learn more about programming in Rust by reading [The Rust Programming Language][rust-book].
+
+[rust]: https://www.rust-lang.org/
+[rustup]: https://rustup.rs/
+[rust-analyzer]: https://rust-analyzer.github.io/
+[intellij-rust]: https://intellij-rust.github.io/
+[rust-book]: https://doc.rust-lang.org/book/
+
+## Workflow
+
+Follow these steps to contribute to the project:
+
+1. Make a fork of the [Pikelet repository][pikelet-repo].
+1. Within your fork, create a branch for your contribution. Use a meaningful name.
+1. Create your contribution, meeting all [contribution quality standards](#quality-standards).
+1. Ensure all the tests pass (`cargo test`).
+1. [Create a pull request][create-a-pr] against the `master` branch of the repository.
+1. Once the pull request is reviewed and CI passes, it will be merged.
+
+[pikelet-repo]: https://github.com/pikelet-lang/pikelet/
+[create-a-pr]: https://help.github.com/articles/creating-a-pull-request-from-a-fork/
+
+## Quality Standards
+
+Most quality and style standards are checked automatically by the CI build.
+Contributions should:
+
+- Separate each **logical change** into its own commit.
+- Include tests for any new functionality in your pull request.
+- Document public functions.
+- Format code with `cargo fmt`.
+- Avoid adding `unsafe` code.
+  If it is necessary, provide an explanatory comment on any `unsafe` block explaining its rationale and why it's safe.
+- Add a descriptive message for each commit. Follow [these commit message guidelines][commit-messages].
+- Document your pull requests. Include the reasoning behind each change, and the testing done.
+
+[commit-messages]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 ![Pikelet Mascot][pikelet-mascot]
 
-[pikelet-mascot]: assets/pikelet.png
+[pikelet-mascot]: ./book/assets/pikelet.png
 
 [![Actions Status][actions-badge]][actions-url]
 [![Matrix][matrix-badge]][matrix-lobby]

diff --git a/book/.gitignore b/book/.gitignore
@@ -0,0 +1,9 @@
+# mdBook
+/build
+
+# Yarn
+/node_modules
+
+# Parcel
+/.cache
+/dist
diff --git a/book/README.md b/book/README.md
@@ -0,0 +1,45 @@
+# Pikelet Book
+
+To build the book, you will first need to [install mdBook][install-mdbook] and [mdbook-linkcheck]:
+
+```sh
+cargo install mdbook mdbook-linkcheck
+```
+
+Note that for consistency we use specific versions of these tools on CI,
+so the one you install might be newer than the one used to build and deploy the book.
+To check the versions we currently assume, look at the [workflows directory](../.github/workflows).
+
+## Building additional JavaScript
+
+In order to highlight the Fathom code examples in the book we override mdBook's built-in [highlight.js] with our own.
+To build the highlighting code, run the following commands using [Yarn]:
+
+```sh
+yarn workspace book install
+yarn workspace book build
+```
+
+You will need to rebuild the book or restart the mdBook server for changes to take effect.
+
+[highlight.js]: https://highlightjs.org/
+[Yarn]: (https://yarnpkg.com/)
+
+## Running the mdBook server
+
+You can then serve the documentation locally by calling the [`serve` command][mdbook-serve]
+from the `book` directory:
+
+```sh
+mdbook serve
+```
+
+Alternatively it can be called from the root of the repository:
+
+```sh
+mdbook serve book
+```
+
+[install-mdbook]: https://rust-lang.github.io/mdBook/cli/index.html#install-cratesio-version
+[mdbook-serve]: https://rust-lang.github.io/mdBook/cli/serve.html
+[mdbook-linkcheck]: https://github.com/Michael-F-Bryan/mdbook-linkcheck#getting-started
diff --git a/assets/pikelet.png → book/assets/pikelet.png b/assets/pikelet.png → book/assets/pikelet.png
diff --git a/book/book.toml b/book/book.toml
@@ -0,0 +1,36 @@
+[book]
+title = "Pikele Book"
+authors = ["YesLogic Pty. Ltd. <info@yeslogic.com>"]
+description = "Documentation for the Pikelet programming language"
+language = "en"
+multilingual = false
+src = "src"
+
+[build]
+build-dir = "build"
+
+[output.html]
+additional-js = [
+    "dist/index.js",
+]
+
+[output.html.redirect]
+"/installation/index.html" = "./guide/installation.html"
+"/language/index.html" = "./reference.html"
+# "/language/conditionals.html" = TODO
+"/language/functions.html" = "./reference/functions.html"
+"/language/records.html" = "./reference/records.html"
+# "/language/bindings.html" = TODO
+# "/language/type-inference.html" = TODO
+"/language/universes.html" = "./reference/universes.html"
+"/appendix/index.html" = "./specification.html"
+"/appendix/design.html" = "./development/design-goals.html"
+"/appendix/theory.html" = "./specification.html"
+# "/appendix/influences.html" = TODO
+# "/appendix/references.html" = TODO
+
+# [output.linkcheck]
+# exclude = [
+#     '\./contributing\.md', # Bypass `traverse-parent-directories` for this symlink
+#     '\./code-of-conduct\.md', # Bypass `traverse-parent-directories` for this symlink
+# ]
diff --git a/book/index.js b/book/index.js
@@ -0,0 +1,49 @@
+import hljs from "highlight.js/lib/core";
+
+hljs.registerLanguage("pikelet", (hljs) => {
+  const KEYWORDS = {
+    keyword: "as fun Fun record Record",
+    built_in: "Type Bool true false U8 U16 U32 U64 S8 S16 S32 S64 F32 F64 String Char Array List",
+  };
+
+  const CHARACTER = {
+    className: "string",
+    begin: /'([^'\\]|\\.)*'/,
+  };
+  const STRING = {
+    className: "string",
+    begin: /"([^"\\]|\\.)*"/,
+  };
+  const NUMBER = {
+    className: "number",
+    begin: /\b[-+]?[0-9][a-zA-Z0-9_\.]*\b/,
+    relevance: 0,
+  };
+
+  const COMMENT = {
+    variants: [
+      hljs.COMMENT("--", "$"),
+      hljs.COMMENT("|||", "$"),
+    ],
+  };
+
+  return {
+    name: "Fathom",
+    keywords: KEYWORDS,
+    contains: [
+      STRING,
+      CHARACTER,
+      NUMBER,
+
+      COMMENT,
+
+      { begin: "->|<-" }, // No markup, relevance booster
+    ],
+  };
+});
+
+window.addEventListener("load", (event) => {
+  document
+    .querySelectorAll("code.language-pikelet")
+    .forEach((block) => hljs.highlightBlock(block));
+});
diff --git a/book/package.json b/book/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "book",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "parcel index.js --no-source-maps",
+    "build": "parcel build index.js --no-source-maps"
+  },
+  "devDependencies": {
+    "parcel-bundler": "^1.12.4"
+  },
+  "dependencies": {
+    "highlight.js": "^10.2.0"
+  }
+}
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -0,0 +1,39 @@
+# Summary
+
+[Pikelet](index.md)
+
+- [Guide](./guide.md)
+  - [Installation](./guide/installation.md)
+  - [Using the REPL](./guide/using-the-repl.md)
+  - [Compiling Standalone Programs]()
+  - [Pikelet as a Configuration Language]()
+  - [Pikelet as a Scripting Language]()
+
+- [Reference](./reference.md)
+  - [Comments](./reference/comments.md)
+  - [Keywords](./reference/keywords.md)
+  - [Names](./reference/names.md)
+  - [Builtins](./reference/builtins.md)
+  - [Literals](./reference/literals.md)
+  - [Universes](./reference/universes.md)
+  - [Functions](./reference/functions.md)
+  - [Records](./reference/records.md)
+
+- [Specification](./specification.md)
+  - [Core Language]()
+    - [Semantics]()
+    - [Typing]()
+  - [Surface Language]()
+    - [Elaboration]()
+  - [Textual Representation](./specification/textual-representation.md)
+    - [Lexical Syntax](./specification/textual-representation/lexical-syntax.md)
+    - [Concrete Syntax](./specification/textual-representation/concrete-syntax.md)
+  - [Inspiration](./specification/inspiration.md)
+
+- [Development](./development.md)
+  - [Contributing](./development/contributing.md)
+  - [Code of Conduct](./development/code-of-conduct.md)
+  - [Roadmap](./development/roadmap.md)
+  - [Design](./development/design.md)
+  - [Influences](./development/influences.md)
+  - [Bibliography](./development/bibliography.md)
diff --git a/book/src/development.md b/book/src/development.md
@@ -0,0 +1,12 @@
+# Development
+
+Development documentation for contributors to the Pikelet programming language.
+
+## Summary
+
+- [Contributing](./development/contributing.md)
+- [Code of Conduct](./development/code-of-conduct.md)
+- [Roadmap](./development/roadmap.md)
+- [Design](./development/design.md)
+- [Influences](./development/influences.md)
+- [Bibliography](./development/bibliography.md)
diff --git a/website/docs/reference/bibliography.md → book/src/development/bibliography.md b/website/docs/reference/bibliography.md → book/src/development/bibliography.md
@@ -1,11 +1,4 @@
----
-id: bibliography
-title: Bibliography
-keywords:
-  - docs
-  - reference
-  - pikelet
----
+# Bibliography
 
 The following resources where helpful when designing and building Pikelet.
 

diff --git a/book/src/development/code-of-conduct.md b/book/src/development/code-of-conduct.md
@@ -0,0 +1 @@
+../../../CODE_OF_CONDUCT.md
diff --git a/book/src/development/contributing.md b/book/src/development/contributing.md
@@ -0,0 +1 @@
+../../../CONTRIBUTING.md
diff --git a/book/src/development/design.md b/book/src/development/design.md
@@ -0,0 +1,39 @@
+# Design
+
+## Design Principles
+
+- We aim to empower our users through careful design and great documentation,
+  rather than being driven by what assume is familiar.
+- Pikelet should be able to be progressively disclosed, with surface level features being built out of simpler parts.
+- Pikelet should work well for high level and low level, resource constrained applications.
+- Pikelet should be easy to bootstrap and cross-compile.
+- Pikelet should have excellent compile time error messages and diagnostics.
+- Pikelet programs should not have to pay for things that they do not use.
+- Language features should behave predictably, as opposed to relying on complicated, hard to understand heuristics.
+- Language features should simple to implement, with a high power-to-weight ratio.
+- Language features should work in harmony together.
+
+## Research to Watch
+
+There are a number of exciting areas of research that are worth keeping an eye on:
+
+- Dependent types
+- High performance elaboration
+- Effects and Coeffects
+  - Algebraic Effects and Handlers
+  - Effect Runners
+  - Graded Modal Type Theory
+    - Quantitative Type Theory
+    - Multistage Programming
+- Call by Push Value
+- Codata vs. Data
+- Modular Programming with Dependent Records
+- Fancy Dependencies
+  - Self Types
+  - Dependent Intersection
+  - Very Dependent Types
+- Datatype Generic Programming
+  - Levitated data descriptions
+  - Data Layout Interpretations
+  - Ornamented Data Types
+- Projectional Editors