Improve the proposal repo layout. (#7)

* Improve the proposal repo layout.

 - Change from `.wit.md` files with
   wit-embedded-in-markdown-code-comments to just `.wit` files
   containing just Wit. Feedback from early users so far has been that
   people want to just maintain plain wit.

 - Use the new `--html-in-md` option to generate the prettier HTML
   output in the `.md` file, which is rendered on Github. The specifics
   here may evolve, but overall the idea is:
    - Don't check in `.html` files into the repo, as they can't be
      rendered and as such are confusing.
    - Do check in a generated `.md` file, with as much formatting and
      linkifying as we can get.

The generated HTML has a *lot* of room for improvement. But at least with this
PR the HTML is viewable from the Github UI and it has a table of contents and
the formatting is a little tidier.

* Add a `deps` directory example.

Add an example dependency using a `deps` directory. And rename some
things for clarity.

* Update to wit-abi-0.10.0.

This updates to the 0.3.0 release of wit-bindgen.

.github/workflows/main.yml

@@ -11,6 +11,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
-    - uses: WebAssembly/wit-abi-up-to-date@v10
+    - uses: WebAssembly/wit-abi-up-to-date@v12
       with:
-        wit-abi-tag: wit-abi-0.8.0
+        wit-abi-tag: wit-abi-0.10.0

README.md

@@ -55,6 +55,8 @@ TODO before entering Phase 2.
 
 ### API walk-through
 
+The full API documentation can be found [here](wasi-proposal-template.md).
+
 [Walk through of how someone would use this API.]
 
 #### [Use case 1]

example-world.md

@@ -0,0 +1,72 @@
+<h1><a name="example_world">World example-world</a></h1>
+<ul>
+<li>Imports:
+<ul>
+<li>interface <a href="#example_dep_interface"><code>example-dep-interface</code></a></li>
+<li>interface <a href="#example_interface"><code>example-interface</code></a></li>
+</ul>
+</li>
+</ul>
+<h2><a name="example_dep_interface">Import interface example-dep-interface</a></h2>
+<hr />
+<h3>Types</h3>
+<h4><a name="example_dep_type"><code>type example-dep-type</code></a></h4>
+<p><code>u32</code></p>
+<p>
+## <a name="example_interface">Import interface example-interface</a>
+<p>Short interface description.</p>
+<p>Explanation for developers using the interface API. It should include an
+overview of the API as a whole as well as call out notable items in it,
+for example <a href="#example_api_type"><code>example-api-type</code></a> and <a href="#example_api_function"><code>example-api-function</code></a>.</p>
+<hr />
+<h3>Types</h3>
+<h4><a name="example_dep_type"><code>type example-dep-type</code></a></h4>
+<p><a href="#example_dep_type"><a href="#example_dep_type"><code>example-dep-type</code></a></a></p>
+<p>
+#### <a name="example_api_type">`record example-api-type`</a>
+<p>Short type description</p>
+<p>Explanation for developers using this type. It may be useful to give
+some examples of places in the API where the type is used, such as in
+the arguments and return type of <a href="#example_api_function"><code>example-api-function</code></a>.</p>
+<details>
+<summary>Detailed specification</summary>
+More rigorous specification details for implementers go here, if needed.
+The intention is to keep the developer-oriented docs focused on things that
+most developers will need to be aware of, while putting bulkier descriptions
+of precise behavior here.
+</details>
+<h5>Record Fields</h5>
+<ul>
+<li>
+<p><a name="example_api_type.field0"><code>field0</code></a>: <code>u64</code></p>
+<p>A description of a field.
+</li>
+<li>
+<p><a name="example_api_type.field1"><code>field1</code></a>: <code>string</code></p>
+<p>A description of another field.
+</li>
+</ul>
+<hr />
+<h3>Functions</h3>
+<h4><a name="example_api_function"><code>example-api-function: func</code></a></h4>
+<p>Short function description</p>
+<p>Explanation for developers using the API. This should describe the
+arguments which in this function are <code>arg0</code>, <code>arg1</code>, and <code>arg2</code>, and the
+return value.</p>
+<details>
+<summary>Detailed specification</summary>
+Similar to the details section above, this is meant for more rigorous
+specification details for implementors. This may explain what a compliant
+implementation MUST do, such as never returning an earlier result from a
+later call, for example.
+</details>
+<h5>Params</h5>
+<ul>
+<li><a name="example_api_function.arg0"><code>arg0</code></a>: <a href="#example_api_type"><a href="#example_api_type"><code>example-api-type</code></a></a></li>
+<li><a name="example_api_function.arg1"><code>arg1</code></a>: <code>string</code></li>
+<li><a name="example_api_function.arg2"><code>arg2</code></a>: <a href="#example_dep_type"><a href="#example_dep_type"><code>example-dep-type</code></a></a></li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="example_api_function.0"></a> result&lt;<a href="#example_api_type"><a href="#example_api_type"><code>example-api-type</code></a></a>&gt;</li>
+</ul>

wit/deps/example-dep/example-api.wit

@@ -0,0 +1,6 @@
+// An example dependency, showing how these look. Actual proposals should
+// delete this file and add their actual dependencies in the `deps` directory.
+
+interface example-dep-interface {
+    type example-dep-type = u32
+}

wit/example.wit

@@ -0,0 +1,59 @@
+// Instructions for filling in this file:
+//
+//  - Delete all these `//` comments, up to the first `///` comment.
+//
+//  - Replace the remaining contents below with [Wit] code describing
+//    `interface`s and/or `world`s, using the same formatting style.
+//
+// If you want to include examples of the API in use, these should be in the
+// README.md at the root of the repository and linked to from this file.
+//
+// [Wit]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md
+
+/// Short interface description.
+///
+/// Explanation for developers using the interface API. It should include an
+/// overview of the API as a whole as well as call out notable items in it,
+/// for example `example-api-type` and `example-api-function`.
+default interface example-interface {
+    use example-dep.example-api.example-dep-interface.{example-dep-type}
+
+    /// Short type description
+    ///
+    /// Explanation for developers using this type. It may be useful to give
+    /// some examples of places in the API where the type is used, such as in
+    /// the arguments and return type of `example-api-function`.
+    ///
+    /// <details>
+    /// <summary>Detailed specification</summary>
+    /// More rigorous specification details for implementers go here, if needed.
+    /// The intention is to keep the developer-oriented docs focused on things that
+    /// most developers will need to be aware of, while putting bulkier descriptions
+    /// of precise behavior here.
+    /// </details>
+    record example-api-type {
+        /// A description of a field.
+        field0: u64,
+        /// A description of another field.
+        field1: string,
+    }
+
+    /// Short function description
+    ///
+    /// Explanation for developers using the API. This should describe the
+    /// arguments which in this function are `arg0`, `arg1`, and `arg2`, and the
+    /// return value.
+    ///
+    /// <details>
+    /// <summary>Detailed specification</summary>
+    /// Similar to the details section above, this is meant for more rigorous
+    /// specification details for implementors. This may explain what a compliant
+    /// implementation MUST do, such as never returning an earlier result from a
+    /// later call, for example.
+    /// </details>
+    example-api-function: func(
+        arg0: example-api-type,
+        arg1: string,
+        arg2: example-dep-type,
+    ) -> result<example-api-type>
+}

wit/world.wit

@@ -0,0 +1,10 @@
+// If the repository defines `interface`s, this file can define a minimal world
+// which contains those interfaces, to allow documentation to be generated for
+// them.
+//
+// Proposals should remove these `//` commments, and edit the `world` name and
+// imports below to pull in their own `interface`s.
+
+default world example-world {
+    import example-interface: pkg.example.example-interface
+}