This is a tool to turn your code into a specification. It is language agnostic, but you need Cargo (which you can install via Rustup) to use it. To see it in action, just look at the code in this codebase, as well as the spec it produced. You can read more about the concepts behind it in the blogpost The code is the specification: introducing cargo-spec.
initialize. To start your specification, you need two files: a Specification.toml configuration file and a template containing your specification written in markdown.
You can create these in your current directory via cargo spec new <NAME>, or on a given path via cargo spec init <PATH>:
```console $ cargo install cargo-spec $ cargo spec new
Created new specification as Specification.toml and specification_template.md
You can now run cargo spec build to create the specification file
```
build. Building your specification will convert your template into the desired format (markdown by default), at some path (specification.md by default):
```console $ cargo spec build
=> html output saved at ./specification.md ```
You can also watch for any changes:
```console $ cargo spec watch
=> html output saved at ./specification.md ```
cargo-spec's philosophy stems from the fact that most protocols often come from a reference implementation. That reference implementation tends to change, and as you want your spec to be up to date you will want to keep parts of the spec as close to the code as possible.
cargo-spec allows you to write your specification as a markdown file, and extract special "spec comments" from your code to fill in sections of your spec.
To run cargo-spec, you need a Specification.toml file.
Although you can specify a different filename via the --specification-path option.
```toml [specification]
name = "Consensus" description = "This specification describes the consensus protocol." version = "0.1.0" authors = ["David Wong"]
[config]
template = "template.md"
[sections]
datastructures = "src/datastructures.rs" abstract_modules = "@/src/module.rs" # you can also use absolute paths (you need to be in a git repo) ```
A template is simply a markdown file that contains placeholders. The path of the template must be specified in the Specification.toml file.
By default the cargo spec new <NAME> (or cargo spec init <PATH>) command will use specification_template.md as template.
```markdown
Here's the consensus spec
{sections.data_structures}
{sections.abstract_modules} ```
Cargo-spec recognizes comments starting with the tilde ~.
For example, in rust:
rust
//~ some specification text
in Python:
```python
```
or in OCaml:
ocaml
(*~ some spec *)
While cargo-spec is language-agnostic, it does not support all type of comments. Post an issue if it does not work for the language you're using.
It can be tiring to indent manually your comments to create nested lists:
rust
//~ - a list
//~ - a nested list
instead, simply add ~ at the start of your spec comment to add indentation:
rust
//~ - a list
//~~ - a nested list
You can import blocks of code by surrounding them with //~ spec:startcode and //~ spec:endcode:
rust
//~ spec:startcode
struct SomeStruct {
a: u8,
b: u64,
}
//~ spec:endcode
You'll most likely want to enforce that PRs contains up-to-date specification files checked-in. You can do this for example with this Github Action:
```yml name: Check specifications
on: pull_request:
jobs: run_checks: runs-on: ubuntu-latest name: Enforce up-to-date specification files steps:
- name: Checkout PR
uses: actions/checkout@v2
- name: Set up cargo/rust
uses: actions-rs/toolchain@v1
- name: Check that up-to-date specification is checked in
run: |
cargo install cargo-spec
cd <spec_folder>
cargo spec build
git diff --exit-code
```
The Cargo spec Project is dual-licensed under Apache 2.0 and MIT terms. See LICENSE-APACHE and LICENSE-MIT for details.