Add book documentation skeleton and auto-publish from CI (bytecodeall…

…iance#435)

This commit adds the skeleton of a new set of documentation for
`wasmtime` in the existing `docs` directory. This documentation is
organized and compiled with [mdbook] which the Rust project uses for
most of its own documentation as well. At a previous meeting we
brainstormed a rough skeleton of what the documentation in this book
would look like, and I've transcribed that here for an example of how
this is rendered and how it can be laid out. No actual documentation is
written yet.

This commit also additionally adds necessary support to auto-publish
both this book documentation and API documentation every time a commit
is pushed to the `master` branch. All HTML will be automatically pushed
to the `gh-pages` branch so long as the CI passes, and this should get
deployed to https://cranestation.github.io/wasmtime.

I've done a few dry-runs and I think this'll all work, but we'll likely
tweak a few things here and there after running this through CI to make
sure everything looks just as we'd like. My hope though is that after
this lands we can start actually filling out all the documentation and
being able to review it as well.

[mdbook]: https://crates.io/crates/mdbook

.azure-pipelines.yml

@@ -151,12 +151,38 @@ jobs:
   - template: ci/azure-prepare-centos-6.yml
   - template: ci/azure-build-wheels.yml
 
+- job: Doc_book
+  displayName: "Doc - build the book"
+  steps:
+    - script: |
+        set -e
+        curl -L https://github.com/rust-lang-nursery/mdBook/releases/download/v0.3.1/mdbook-v0.3.1-x86_64-unknown-linux-gnu.tar.gz | tar xzf -
+        echo "##vso[task.prependpath]$PWD"
+      displayName: "Install mdbook"
+    - script: (cd docs && mdbook build)
+    - task: PublishPipelineArtifact@1
+      inputs:
+        artifactName: doc_book
+        path: docs/book
+
+- job: Doc_api
+  displayName: "Doc - build the API documentation"
+  steps:
+    - template: ci/azure-install-rust.yml
+    - script: cargo doc
+    - task: PublishPipelineArtifact@1
+      inputs:
+        artifactName: doc_api
+        path: target/doc
+
 - job: Publish
   dependsOn:
   - Build
   - Build_wheels
   - Build_linux
   - Build_linux_wheels
+  - Doc_book
+  - Doc_api
   condition: and(succeeded(), in(variables['Build.Reason'], 'IndividualCI', 'BatchedCI'))
   steps:
   # Checking out the sources is needed to be able to delete the "dev" tag, see below.
@@ -166,6 +192,21 @@ jobs:
   - task: DownloadPipelineArtifact@1
     inputs:
       targetPath: $(Build.ArtifactStagingDirectory)
+  - script: |
+      set -e
+      mv $(Build.ArtifactStagingDirectory)/doc_book gh-pages
+      mv $(Build.ArtifactStagingDirectory)/doc_api gh-pages/api
+    displayName: Create gh-pages directory
+  - script: |
+      set -e
+      cd gh-pages
+      git init
+      cp ../.git/config .git
+      git add .
+      git -c user.name='ci' -c user.email='ci' commit -m init
+      git push -f -q https://github.com/CraneStation/wasmtime HEAD:gh-pages
+    displayName: Publish gh-pages directory
+    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/master'))
   - script: |
       echo "##vso[task.setvariable variable=tagName;]`echo $BUILD_SOURCEBRANCH | sed -e 's|refs/tags/||'`"
     condition: startsWith(variables['Build.SourceBranch'], 'refs/tags/')

.gitignore

@@ -10,3 +10,4 @@ cranelift.dbg*
 rusty-tags.*
 *~
 \#*\#
+docs/book

docs/SUMMARY.md

@@ -0,0 +1,35 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Tutorial](./tutorial.md)
+  - [Creating `hello-world.wasm`](./tutorial-create-hello-world.md)
+  - [Running `hello-world.wasm`](./tutorial-run-hello-world.md)
+- [Examples](./examples.md)
+  - [Markdown parser](./examples-markdown.md)
+- [Using WebAssembly from your lanugage](./lang.md)
+  - [Python](./lang-python.md)
+  - [.NET](./lang-dotnet.md)
+  - [Rust](./lang-rust.md)
+  - [Bash](./lang-bash.md)
+- [Using the `wasmtime` CLI](./cli.md)
+  - [Installation](./cli-install.md)
+  - [CLI Options](./cli-options.md)
+  - [Cache Configuration](./cli-cache.md)
+- [Writing WebAssembly](./wasm.md)
+  - [Rust](./wasm-rust.md)
+  - [C/C++](./wasm-c.md)
+  - [Example: Markdown Parser](./wasm-markdown.md)
+- [Embedding Wasmtime](embed.md)
+  - [Rust API](./embed-rust.md)
+  - [C/C++ API](./embed-c.md)
+- [Stability](stability.md)
+  - [Release Process](./stability-release.md)
+  - [Platform Support](./stability-platform-support.md)
+- [Security](security.md)
+  - [Disclosure Policy](./security-disclosure.md)
+  - [Sandboxing](./security-sandboxing.md)
+- [Contributing](contributing.md)
+  - [Building](./contributing-building.md)
+  - [CI](./contributing-ci.md)
+  - [Governance](./contributing-governance.md)
+  - [Code of Conduct](./contributing-coc.md)

docs/book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["The Wasmtime Project Developers"]
+multilingual = false
+src = "."
+title = "Wasmtime"

docs/cli-cache.md

@@ -0,0 +1,3 @@
+# Cache Configuration of `wasmtime`
+
+... more coming soon

docs/cli-install.md

@@ -0,0 +1,3 @@
+# Installing `wasmtime`
+
+... more coming soon

docs/cli-options.md

@@ -0,0 +1,3 @@
+# CLI Options for `wasmtime`
+
+... more coming soon

docs/cli.md

@@ -0,0 +1,3 @@
+# Using the `wasmtime` CLI
+
+... more coming soon

docs/contributing-building.md

@@ -0,0 +1,3 @@
+# Building
+
+... more coming soon

docs/contributing-ci.md

@@ -0,0 +1,3 @@
+# CI
+
+... more coming soon

docs/contributing-coc.md

@@ -0,0 +1,3 @@
+# Code of Conduct
+
+... more coming soon

docs/contributing-governance.md

@@ -0,0 +1,3 @@
+# Governance
+
+... more coming soon

docs/contributing.md

@@ -0,0 +1,3 @@
+# Contributing
+
+... more coming soon

docs/embed-c.md

@@ -0,0 +1,4 @@
+# Embedding Wasmtime in C
+
+... more coming soon
+

docs/embed-rust.md

@@ -0,0 +1,3 @@
+# Embedding Wasmtime in Rust
+
+... more coming soon

docs/embed.md

@@ -0,0 +1,3 @@
+# Embedding Wasmtime
+
+... more coming soon

docs/examples-markdown.md

@@ -0,0 +1,3 @@
+# Markdown Parser
+
+... more coming soon

docs/examples.md

@@ -0,0 +1,5 @@
+# Examples
+
+This is an explanation of all examples to come
+
+... more coming soon

docs/introduction.md

@@ -0,0 +1,3 @@
+# Introduction
+
+... more coming soon

docs/lang-bash.md

@@ -0,0 +1,3 @@
+# Using WebAssembly from Bash
+
+... more coming soon

docs/lang-dotnet.md

@@ -0,0 +1,3 @@
+# Using WebAssembly from .NET
+
+... more coming soon

docs/lang-python.md

@@ -0,0 +1,3 @@
+# Using WebAssembly from Python
+
+... more coming soon

docs/lang-rust.md

@@ -0,0 +1,3 @@
+# Using WebAssembly from Rust
+
+... more coming soon

docs/lang.md

@@ -0,0 +1,3 @@
+# Using WebAssembly from your Language
+
+... more coming soon

docs/security-disclosure.md

@@ -0,0 +1,3 @@
+# Disclosure Policy
+
+... more coming soon

docs/security-sandboxing.md

@@ -0,0 +1,3 @@
+# Sandboxing
+
+... more coming soon

docs/security.md

@@ -0,0 +1,3 @@
+# Security
+
+... more coming soon

docs/stability-platform-support.md

@@ -0,0 +1,3 @@
+# Platform Support
+
+... more coming soon

docs/stability-release.md

@@ -0,0 +1,3 @@
+# Release Process
+
+... more coming soon

docs/stability.md

@@ -0,0 +1,3 @@
+# Stability
+
+... more coming soon

docs/tutorial-create-hello-world.md

@@ -0,0 +1,3 @@
+# Creating `hello-world.wasm`
+
+... more coming soon

docs/tutorial-run-hello-world.md

@@ -0,0 +1,3 @@
+# Running `hello-world.wasm` with Wasmtime
+
+... more coming soon

docs/tutorial.md

@@ -0,0 +1,3 @@
+# Tutorial
+
+... more coming soon

docs/wasm-c.md

@@ -0,0 +1 @@
+# C/C++

docs/wasm-markdown.md

@@ -0,0 +1 @@
+# Example: Markdown Parser

docs/wasm-rust.md

@@ -0,0 +1 @@
+# Rust

docs/wasm.md

@@ -0,0 +1 @@
+# Writing WebAssembly