gianluigip/spectacle

Living Documentation for Distributed Systems

Spectacle

Living Documentation for Distributed Systems

In modern distributed systems the behavior of the product is defined across multiple components and services, and usually developed by multiple teams, as a result, the documentation is fragmented and difficult to find.

Additionally, the system tends to change faster than the documentation which makes the latter unreliable.

Spectacle provides a solution for generating documentation from the multiple codebases in a modern system and then storing it in a central repository that anyone can access.

It has two main components:

• spectacle-dsl: a Kotlin lib for transforming regular tests into specs that can be published to a central repository of specifications.
• spectacle-central: a repository for specifications that allow to find and share the behaviour of all the features in the system.

Spectacle follows the philosophy that only the code and by extension the tests provide accurate documentation of the system, so it provides a DSL for writing readable tests that can be published into a central repository to allows everyone to review.

Spectacle DSL

A Kotlin multiplatform library for generating documentation from tests and Markdown files, it can be used as a standalone tool for improving the readability of tests or in combination with Spectacle Central to generate living documentation.

Add dependencies:

  testImplementation("io.github.gianluigip:spectacle-dsl-bdd:VERSION")
  testImplementation("io.github.gianluigip:spectacle-dsl-assertions:VERSION")
  testImplementation("io.github.gianluigip:spectacle-dsl-publisher:VERSION")
  testImplementation("io.github.gianluigip:spectacle-dsl-http:VERSION")
  testImplementation("io.github.gianluigip:spectacle-dsl-protobuf:VERSION")

Example of a JVM spec class:

@Feature("First Feature", description = "Description defining the feature.")
@ExtendWith(JUnitSpecificationReporter::class)
class JunitExampleTest {

    @Test
    @Specification
    fun `DSL allow to write specs with minimum overhead`() =
        given("a test with multiple steps") {
        } whenever "it executes" run {
        } then "it should register all the BDD steps" runAndFinish {
        }
}

Review Spectacle DSL README for more details.

Spectacle Central

Repository for the living documentation generated by Spectacle DSL, it allows to centralize the documentation generated from multiple executions of the DSL across multiple repositories, so even though the docs are generated from multiple sources it can be queried from a central place which increase the value for the organization as a whole.

Live Demo

• Username: guest
• Password: guest

Review Spectacle Central README for more details.