Facilitates the creation of living documentation by transforming tests into specifications stored in a central repository, ensuring accurate, accessible, and centralized 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.
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.
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.
guestguestReview Spectacle Central README for more details.
Surfaced from shared tags and platforms — no rankings paid for.