Autogenerate README based on library documentation with cargo-readme (#23)

As discussed just last week it's annoying to keep the README and library
docs in sync, in particular because the code in `README.md` isn't
build-tested like the module docs.  Fortunately `cargo-readme` feeds two
birds with one scone: it bases (part of) `README.md` on the module
documentation - which was tested with `cargo test` just prior.

Author: MarijnS95

.github/workflows/ci.yml

@@ -70,3 +70,29 @@ jobs:
         with:
           command: clippy
           args: --workspace --all-targets --all-features -- -D warnings
+
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+      - name: Use cached cargo-readme
+        uses: actions/cache@v2
+        id: cargo-readme-cache
+        with:
+          path: ~/.cargo/bin/cargo-readme
+          key: ${{ runner.os }}-cargo-readme
+      - name: Install cargo-readme
+        if: steps.cargo-readme-cache.outputs.cache-hit != 'true'
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: cargo-readme
+      - name: Check if README.md is up-to-date
+        run: |
+          cargo readme > README.md
+          git diff --quiet || (echo '::error::Generated README is different, please regenerate with `cargo readme > README.md`'; git diff; false)

README.md

@@ -1,11 +1,12 @@
-# 📒 gpu-allocator
+📒 gpu-allocator
+=
 
 [![Actions Status](https://github.com/Traverse-Research/gpu-allocator/workflows/CI/badge.svg)](https://github.com/Traverse-Research/gpu-allocator/actions)
+[![Latest version](https://img.shields.io/crates/v/gpu-allocator.svg)](https://crates.io/crates/gpu-allocator)
 [![Docs](https://docs.rs/gpu-allocator/badge.svg)](https://docs.rs/gpu-allocator/)
 [![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE-MIT)
 [![LICENSE](https://img.shields.io/badge/license-apache-blue.svg)](LICENSE-APACHE)
 [![Contributor Covenant](https://img.shields.io/badge/contributor%20covenant-v1.4%20adopted-ff69b4.svg)](../main/CODE_OF_CONDUCT.md)
-[![Latest version](https://img.shields.io/crates/v/gpu-allocator.svg)](https://crates.io/crates/gpu-allocator)
 
 [![Banner](banner.png)](https://traverseresearch.nl)
 
@@ -14,10 +15,12 @@
 gpu-allocator = "0.6.0"
 ```
 
-## Setting up the allocator for Vulkan
+This crate provides a fully written in Rust memory allocator for Vulkan, and will provide one for DirectX 12 in the future.
+
+### Setting up the Vulkan memory allocator
+
 ```rust
-use ash::version::{DeviceV1_0, EntryV1_0, InstanceV1_0};
-use ash::vk;
+use gpu_allocator::*;
 
 let mut allocator = VulkanAllocator::new(&VulkanAllocatorCreateDesc {
     instance,
@@ -27,30 +30,33 @@ let mut allocator = VulkanAllocator::new(&VulkanAllocatorCreateDesc {
 });
 ```
 
-## Vulkan allocation example
+### Simple Vulkan allocation example
+
 ```rust
+use gpu_allocator::*;
+
+
 // Setup vulkan info
 let vk_info = vk::BufferCreateInfo::builder()
     .size(512)
     .usage(vk::BufferUsageFlags::STORAGE_BUFFER);
 
-let buffer = unsafe { device.create_buffer(&vk_info, None) }?;
+let buffer = unsafe { device.create_buffer(&vk_info, None) }.unwrap();
 let requirements = unsafe { device.get_buffer_memory_requirements(buffer) };
 
-
 let allocation = allocator
     .allocate(&AllocationCreateDesc {
         name: "Example allocation",
         requirements,
         location: MemoryLocation::CpuToGpu,
         linear: true, // Buffers are always linear
-    })?;
+    }).unwrap();
 
 // Bind memory to the buffer
-unsafe { device.bind_buffer_memory(buffer, allocation.memory(), allocation.offset())? };
+unsafe { device.bind_buffer_memory(buffer, allocation.memory(), allocation.offset()).unwrap() };
 
 // Cleanup
-allocator.free(allocation)?;
+allocator.free(allocation).unwrap();
 unsafe { device.destroy_buffer(buffer, None) };
 ```
 

README.tpl

@@ -0,0 +1,37 @@
+📒 {{crate}}
+=
+
+[![Actions Status](https://github.com/Traverse-Research/gpu-allocator/workflows/CI/badge.svg)](https://github.com/Traverse-Research/gpu-allocator/actions)
+[![Latest version](https://img.shields.io/crates/v/gpu-allocator.svg)](https://crates.io/crates/gpu-allocator)
+[![Docs](https://docs.rs/gpu-allocator/badge.svg)](https://docs.rs/gpu-allocator/)
+[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE-MIT)
+[![LICENSE](https://img.shields.io/badge/license-apache-blue.svg)](LICENSE-APACHE)
+[![Contributor Covenant](https://img.shields.io/badge/contributor%20covenant-v1.4%20adopted-ff69b4.svg)](../main/CODE_OF_CONDUCT.md)
+
+[![Banner](banner.png)](https://traverseresearch.nl)
+
+```toml
+[dependencies]
+gpu-allocator = "0.6.0"
+```
+
+{{readme}}
+
+### License
+
+Licensed under either of
+
+* Apache License, Version 2.0, ([LICENSE-APACHE](../master/LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+* MIT license ([LICENSE-MIT](../master/LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Alternative libraries
+* [vk-mem-rs](https://github.com/gwihlidal/vk-mem-rs)
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the Apache-2.0
+license, shall be dual licensed as above, without any additional terms or
+conditions.

release.toml

@@ -7,4 +7,5 @@ sign-tag = true
 
 pre-release-replacements = [
   {file="README.md", search="gpu-allocator = .*", replace="{{crate_name}} = \"{{version}}\""},
-]
+  {file="README.tpl", search="gpu-allocator = .*", replace="{{crate_name}} = \"{{version}}\""},
+]