From bf526b62d3b3c89aae182f553089468a1a493640 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 29 Oct 2019 09:55:51 -0500 Subject: [PATCH] Add book documentation skeleton and auto-publish from CI (#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 | 41 +++++++++++++++++++++++++++++ .gitignore | 1 + docs/SUMMARY.md | 35 ++++++++++++++++++++++++ docs/book.toml | 5 ++++ docs/cli-cache.md | 3 +++ docs/cli-install.md | 3 +++ docs/cli-options.md | 3 +++ docs/cli.md | 3 +++ docs/contributing-building.md | 3 +++ docs/contributing-ci.md | 3 +++ docs/contributing-coc.md | 3 +++ docs/contributing-governance.md | 3 +++ docs/contributing.md | 3 +++ docs/embed-c.md | 4 +++ docs/embed-rust.md | 3 +++ docs/embed.md | 3 +++ docs/examples-markdown.md | 3 +++ docs/examples.md | 5 ++++ docs/introduction.md | 3 +++ docs/lang-bash.md | 3 +++ docs/lang-dotnet.md | 3 +++ docs/lang-python.md | 3 +++ docs/lang-rust.md | 3 +++ docs/lang.md | 3 +++ docs/security-disclosure.md | 3 +++ docs/security-sandboxing.md | 3 +++ docs/security.md | 3 +++ docs/stability-platform-support.md | 3 +++ docs/stability-release.md | 3 +++ docs/stability.md | 3 +++ docs/tutorial-create-hello-world.md | 3 +++ docs/tutorial-run-hello-world.md | 3 +++ docs/tutorial.md | 3 +++ docs/wasm-c.md | 1 + docs/wasm-markdown.md | 1 + docs/wasm-rust.md | 1 + docs/wasm.md | 1 + 37 files changed, 176 insertions(+) create mode 100644 docs/SUMMARY.md create mode 100644 docs/book.toml create mode 100644 docs/cli-cache.md create mode 100644 docs/cli-install.md create mode 100644 docs/cli-options.md create mode 100644 docs/cli.md create mode 100644 docs/contributing-building.md create mode 100644 docs/contributing-ci.md create mode 100644 docs/contributing-coc.md create mode 100644 docs/contributing-governance.md create mode 100644 docs/contributing.md create mode 100644 docs/embed-c.md create mode 100644 docs/embed-rust.md create mode 100644 docs/embed.md create mode 100644 docs/examples-markdown.md create mode 100644 docs/examples.md create mode 100644 docs/introduction.md create mode 100644 docs/lang-bash.md create mode 100644 docs/lang-dotnet.md create mode 100644 docs/lang-python.md create mode 100644 docs/lang-rust.md create mode 100644 docs/lang.md create mode 100644 docs/security-disclosure.md create mode 100644 docs/security-sandboxing.md create mode 100644 docs/security.md create mode 100644 docs/stability-platform-support.md create mode 100644 docs/stability-release.md create mode 100644 docs/stability.md create mode 100644 docs/tutorial-create-hello-world.md create mode 100644 docs/tutorial-run-hello-world.md create mode 100644 docs/tutorial.md create mode 100644 docs/wasm-c.md create mode 100644 docs/wasm-markdown.md create mode 100644 docs/wasm-rust.md create mode 100644 docs/wasm.md diff --git a/.azure-pipelines.yml b/.azure-pipelines.yml index fdf6417d25..b913ccdd03 100644 --- a/.azure-pipelines.yml +++ b/.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/') diff --git a/.gitignore b/.gitignore index e7c8fee3e0..9821c9fcd1 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ cranelift.dbg* rusty-tags.* *~ \#*\# +docs/book diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000000..a58c615421 --- /dev/null +++ b/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) diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000000..9fa32dfb63 --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,5 @@ +[book] +authors = ["The Wasmtime Project Developers"] +multilingual = false +src = "." +title = "Wasmtime" diff --git a/docs/cli-cache.md b/docs/cli-cache.md new file mode 100644 index 0000000000..f0d8e189e7 --- /dev/null +++ b/docs/cli-cache.md @@ -0,0 +1,3 @@ +# Cache Configuration of `wasmtime` + +... more coming soon diff --git a/docs/cli-install.md b/docs/cli-install.md new file mode 100644 index 0000000000..34fae6f50b --- /dev/null +++ b/docs/cli-install.md @@ -0,0 +1,3 @@ +# Installing `wasmtime` + +... more coming soon diff --git a/docs/cli-options.md b/docs/cli-options.md new file mode 100644 index 0000000000..3b7926b440 --- /dev/null +++ b/docs/cli-options.md @@ -0,0 +1,3 @@ +# CLI Options for `wasmtime` + +... more coming soon diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000000..c12e0bc9d5 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,3 @@ +# Using the `wasmtime` CLI + +... more coming soon diff --git a/docs/contributing-building.md b/docs/contributing-building.md new file mode 100644 index 0000000000..02861c7b48 --- /dev/null +++ b/docs/contributing-building.md @@ -0,0 +1,3 @@ +# Building + +... more coming soon diff --git a/docs/contributing-ci.md b/docs/contributing-ci.md new file mode 100644 index 0000000000..a63df0b73a --- /dev/null +++ b/docs/contributing-ci.md @@ -0,0 +1,3 @@ +# CI + +... more coming soon diff --git a/docs/contributing-coc.md b/docs/contributing-coc.md new file mode 100644 index 0000000000..3fcb32caca --- /dev/null +++ b/docs/contributing-coc.md @@ -0,0 +1,3 @@ +# Code of Conduct + +... more coming soon diff --git a/docs/contributing-governance.md b/docs/contributing-governance.md new file mode 100644 index 0000000000..ee381b59f5 --- /dev/null +++ b/docs/contributing-governance.md @@ -0,0 +1,3 @@ +# Governance + +... more coming soon diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000000..6eb2498a2a --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,3 @@ +# Contributing + +... more coming soon diff --git a/docs/embed-c.md b/docs/embed-c.md new file mode 100644 index 0000000000..20c5d65b51 --- /dev/null +++ b/docs/embed-c.md @@ -0,0 +1,4 @@ +# Embedding Wasmtime in C + +... more coming soon + diff --git a/docs/embed-rust.md b/docs/embed-rust.md new file mode 100644 index 0000000000..34d837a1f5 --- /dev/null +++ b/docs/embed-rust.md @@ -0,0 +1,3 @@ +# Embedding Wasmtime in Rust + +... more coming soon diff --git a/docs/embed.md b/docs/embed.md new file mode 100644 index 0000000000..92e6b713af --- /dev/null +++ b/docs/embed.md @@ -0,0 +1,3 @@ +# Embedding Wasmtime + +... more coming soon diff --git a/docs/examples-markdown.md b/docs/examples-markdown.md new file mode 100644 index 0000000000..76c8e56d7f --- /dev/null +++ b/docs/examples-markdown.md @@ -0,0 +1,3 @@ +# Markdown Parser + +... more coming soon diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000000..fbef63c4ad --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,5 @@ +# Examples + +This is an explanation of all examples to come + +... more coming soon diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000000..925cc87a8a --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,3 @@ +# Introduction + +... more coming soon diff --git a/docs/lang-bash.md b/docs/lang-bash.md new file mode 100644 index 0000000000..4ba858521a --- /dev/null +++ b/docs/lang-bash.md @@ -0,0 +1,3 @@ +# Using WebAssembly from Bash + +... more coming soon diff --git a/docs/lang-dotnet.md b/docs/lang-dotnet.md new file mode 100644 index 0000000000..22f901f40d --- /dev/null +++ b/docs/lang-dotnet.md @@ -0,0 +1,3 @@ +# Using WebAssembly from .NET + +... more coming soon diff --git a/docs/lang-python.md b/docs/lang-python.md new file mode 100644 index 0000000000..4c2c10224d --- /dev/null +++ b/docs/lang-python.md @@ -0,0 +1,3 @@ +# Using WebAssembly from Python + +... more coming soon diff --git a/docs/lang-rust.md b/docs/lang-rust.md new file mode 100644 index 0000000000..2bdd548ccf --- /dev/null +++ b/docs/lang-rust.md @@ -0,0 +1,3 @@ +# Using WebAssembly from Rust + +... more coming soon diff --git a/docs/lang.md b/docs/lang.md new file mode 100644 index 0000000000..ab5adf5f48 --- /dev/null +++ b/docs/lang.md @@ -0,0 +1,3 @@ +# Using WebAssembly from your Language + +... more coming soon diff --git a/docs/security-disclosure.md b/docs/security-disclosure.md new file mode 100644 index 0000000000..b584fe24ba --- /dev/null +++ b/docs/security-disclosure.md @@ -0,0 +1,3 @@ +# Disclosure Policy + +... more coming soon diff --git a/docs/security-sandboxing.md b/docs/security-sandboxing.md new file mode 100644 index 0000000000..64c80954ed --- /dev/null +++ b/docs/security-sandboxing.md @@ -0,0 +1,3 @@ +# Sandboxing + +... more coming soon diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000000..68616a8545 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,3 @@ +# Security + +... more coming soon diff --git a/docs/stability-platform-support.md b/docs/stability-platform-support.md new file mode 100644 index 0000000000..024c21e296 --- /dev/null +++ b/docs/stability-platform-support.md @@ -0,0 +1,3 @@ +# Platform Support + +... more coming soon diff --git a/docs/stability-release.md b/docs/stability-release.md new file mode 100644 index 0000000000..0bc16d92a3 --- /dev/null +++ b/docs/stability-release.md @@ -0,0 +1,3 @@ +# Release Process + +... more coming soon diff --git a/docs/stability.md b/docs/stability.md new file mode 100644 index 0000000000..10100e107b --- /dev/null +++ b/docs/stability.md @@ -0,0 +1,3 @@ +# Stability + +... more coming soon diff --git a/docs/tutorial-create-hello-world.md b/docs/tutorial-create-hello-world.md new file mode 100644 index 0000000000..8e290aae76 --- /dev/null +++ b/docs/tutorial-create-hello-world.md @@ -0,0 +1,3 @@ +# Creating `hello-world.wasm` + +... more coming soon diff --git a/docs/tutorial-run-hello-world.md b/docs/tutorial-run-hello-world.md new file mode 100644 index 0000000000..ffe03c7075 --- /dev/null +++ b/docs/tutorial-run-hello-world.md @@ -0,0 +1,3 @@ +# Running `hello-world.wasm` with Wasmtime + +... more coming soon diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 0000000000..3ba6d0fff0 --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,3 @@ +# Tutorial + +... more coming soon diff --git a/docs/wasm-c.md b/docs/wasm-c.md new file mode 100644 index 0000000000..40a32b22a2 --- /dev/null +++ b/docs/wasm-c.md @@ -0,0 +1 @@ +# C/C++ diff --git a/docs/wasm-markdown.md b/docs/wasm-markdown.md new file mode 100644 index 0000000000..20485f2073 --- /dev/null +++ b/docs/wasm-markdown.md @@ -0,0 +1 @@ +# Example: Markdown Parser diff --git a/docs/wasm-rust.md b/docs/wasm-rust.md new file mode 100644 index 0000000000..2f1d5efed1 --- /dev/null +++ b/docs/wasm-rust.md @@ -0,0 +1 @@ +# Rust diff --git a/docs/wasm.md b/docs/wasm.md new file mode 100644 index 0000000000..62ff997e65 --- /dev/null +++ b/docs/wasm.md @@ -0,0 +1 @@ +# Writing WebAssembly