Catalyst Standards

Content

• Catalyst Standards
  • Content
  • What's inside?
  • Requirements
  • Development Environment
    • Prerequisites
    • Install Extra Packages/Tools
  • Building Documentation
  • Writing Documentation
    • Diagrams rendered by kroki.io
    • Material Design admonishments
  • Support
  • License

What's inside?

Standards specific to Project Catalyst.

This is where new catalyst standards are developed before they are promoted to CIPs.

Requirements

Development Environment

Prerequisites

We use the mdbook tool to prepare and format these standards.

• Rust

Install Extra Packages/Tools

This only needs to be done once when the development environment is created.

1. cargo install cargo-binstall --locked : see https://github.com/cargo-bins/cargo-binstall
2. cargo binstall --no-confirm cargo-make : see https://github.com/sagiegurari/cargo-make
3. cargo make install-prereqs

Building Documentation

If you have edited any of the documentation, then it needs to be updated by running:

cargo make build-docs

This will build a local copy of the documentation in ./book/html which can be viewed.

It is also possible to build a live version of the documentation which updates as edited by running:

cargo make view-docs

Writing Documentation

Documents are written as Markdown in the CommonMark dialect and must be linted with markdownlint. This is used to ensure consistent format and avoidance of problematic markdown constructs.

The following extensions to mdbook are enabled to provide richer documentation.

NOTE: Conformance with markdownlint is enforced by CI. The ./.markdownlint.json contains our customizations to the markdown lint rules. Edits to this file from external contributors must be in their own PR, do not include them in a PR which edits documentation. This enables us to review proposed format changes independently on their merits.

• Editor Support
  • VS Code

Diagrams rendered by kroki.io

See mdBook Kroki Preprocessor for details.

• Editor Support
  • VS Code

Material Design admonishments

See mdBook Admonishments.

Support

Post issues and feature requests on the GitHub issue tracker.

License

Licensed under either Apache License](LICENSE-APACHE), Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any Contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.