-
+
-
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
diff --git a/docs/.prettierrc.yaml b/docs/.prettierrc.yaml
deleted file mode 100644
index 68eb9c7c5b..0000000000
--- a/docs/.prettierrc.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-printWidth: 120
-proseWrap: always
-semi: true
-singleQuote: true
-quoteProps: as-needed
-trailingComma: all
diff --git a/docs/assembly.md b/docs/assembly.md
deleted file mode 100644
index f4015a509e..0000000000
--- a/docs/assembly.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# `.jsii` Assemblies
-
-This document describes the contents of the `.jsii` assembly documents generated
-by the `jsii` compiler, and explains the semantics behind the various entities
-it represents. This serves as a reference for front-end language implementors.
-
-## Schema
-
-`.jsii` assemblies are JSON-formatted documents. The specification is hosted
-under the [`jsii-spec`](../packages/jsii-spec) package. Refer to the inline
-documentation in the [`spec.ts`](../packages/jsii-spec/lib/spec.ts) file for
-more information about the general content of the assembly documents.
-
-The most important part of the assembly documentation, which is described in
-detail in this document, is the `types` map, which contains the descriptions of
-all types declared by the `.jsii` assembly. It is a map from `jsii` fully-
-qualified type names to a type specification.
-
-All `boolean` attributes in the document specification are optional, and are
-left out (`undefined`) when `false`.
-
-### Common Attributes
-
-Certain optional attributes are shared by API entities (types and members):
-
-* `docs` - documentation attached to the API entity
- * `deprecated` - contains a message explaining why an API was deprecated
- and/or how users should migrate away
- * `stability` - the stability level of the API entity. The ultimate meaning of
- the stability level is up to the package maintainer, but a baseline
- interpretation of the valid values follows:
- + `experimental` denotes an API that is actively worked on and are not
- subject to semantic versioning gurantees (they may receive breaking
- change on a *minor* version release)
- + `stable` denotes an API that is safe to use in production systems and
- are subject ot semantic versioning guarantees (they may not receive
- breaking changes without a *major* version bump)
- + `deprecated` denotes an API that should no longer be used. The
- `deprecated` entry in the `docs` object should contain a message
- explaining how users should migrate away
- + `external` denotes an API that is not owned by the package's maintainer
- and may change in unexpected ways. Such APIs are usually derived from
- external artifacts, which the package maintainers do not have control
- over.
- * additional entries represent user-defined `JSDoc` tags with meaning defined
- by convention and/or the package maintainer
-* `locationInModule` - coordinates of the declaration in the source
- * `fileName` - the path to the source file, relative to the package root
- * `line` - the line number on which the entity is declared (or the first line
- when a declaration spans multiple lines)
-
-### Types
-
-#### Classes
-
-Attribute | Type | Description
--------------|-------------|----------------------------------------------------
-`kind` |`'class'` |Discriminator to identify classes
-`abstract` |`boolean` |Whether this class is *abstract*
-`assembly` |`string` |The name of the assembly this class is a part of
-`base` |`string` |The fully-qualified name of the parent class of this class
-`fqn` |`string` |The fully-qualified name of the class
-`initializer`|`Constructor`|The class' [constructor]
-`interfaces` |`string[]` |The fully-qualified names of interfaces implemented by this class
-`methods` |`Method[]` |The [methods] declared by this class
-`name` |`string` |The simple name of the class
-`properties` |`Property[]` |The [properties] declared by this class
-
-[constructor]: #constructors
-[interfaces]: #interfaces
-[methods]: #methods
-[properties]: #properties
-
-#### Interfaces
-
-`jsii` interfaces are declarations of type signatures that can be implemented by
-classes. *Interface* names must be prefixed with an `I` (e.g: `IFoo`).
-
-Attribute | Type | Description
--------------|-------------|----------------------------------------------------
-`kind` |`'interface'`|Discriminator to identify interfaces
-`assembly` |`string` |The name of the assembly this interface is a part of
-`fqn` |`string` |The fully-qualified name of the interface
-`interfaces` |`string[]` |The fully-qualified names of interfaces extended by this interface
-`methods` |`Method[]` |The [methods] declared by this interface
-`name` |`string` |The simple name of the interface
-`properties` |`Property[]` |The [properties] declared by this interface
-
-#### Structs (a.k.a. Data Types)
-
-*Structs* (or *Data Types*) are immutable, data-only interfaces:
-* They declare no methods
-* All [properties] they declare are `readonly`
-* They can only implement other *structs*
-* They cannot be extended by interfaces that are not *structs*
-* They cannot be implemented by *classes*
-
-Unlike regular *interfaces*, `jsii` *struct* names are not required to have
-any particular prefix.
-
-Since those are immutable, pure data objects, the `jsii-runtime` exchanges
-instances of those *by value*, instead of *by reference*, allowing to save
-cross-language communication overhead when working with the data.
-
-Attribute | Type | Description
--------------|--------------|----------------------------------------------------
-`kind` |`'interface'` |Discriminator to identify interfaces
-`datatype` |`true` |Indicates a *struct* / *data type* declaration
-`assembly` |`string` |The name of the assembly this struct is a part of
-`fqn` |`string` |The fully-qualified name of the struct
-`interfaces` |`string[]` |The fully-qualified names of *struct* extended by this *struct*
-`name` |`string` |The simple name of the struct
-`properties` |`Property[]` |The [properties] declared by this struct (all `readonly`)
-
-#### Enums
-
-Attribute | Type | Description
--------------|--------------|---------------------------------------------------
-`kind` |`'enum'` |Discriminator to identify enums
-`assembly` |`string` |The name of the assembly this enum is a part of
-`fqn` |`string` |The fully-qualified name of the enum
-`members` |`EnumMember[]`|The [enum members] declared by this enum
-`name` |`string` |The simple name of the enum
-
-[enum members]: #enum-members
-
-### Members
-
-#### Constructors
-
-Attribute | Type | Description
--------------|--------------|---------------------------------------------------
-`overrides` |`string` |The fully-qualified name of the class/interface that declares the overridden constructor
-`parameters` |`Parameter[]` |Parameters of this constructor
-`protected` |`boolean` |Whether this constructor is protected
-`variadic` |`boolean` |Whether the last parameter is `variadic`
-
-#### Enum Members
-
-Attribute | Type | Description
--------------|--------------|---------------------------------------------------
-`name` |`string` |The name of the enum member. Must be `UPPER_SNAKE_CASED`
-
-#### Methods
-
-Attribute | Type | Description
--------------|---------------|--------------------------------------------------
-`abstract` |`boolean` |Whether this method is `abstract`
-`async` |`boolean` |Whether this method is asynchronous
-`name` |`string` |The name of the method
-`overrides` |`string` |The fully-qualified name of the class/interface that declares the overridden method
-`parameters` |`Parameter[]` |Parameters of this method
-`protected` |`boolean` |Whether this method is protected
-`returns` |`OptionalValue`|The return type of the method
-`static` |`boolean` |Whether this method is `static`
-`variadic` |`boolean` |Whether the last parameter is `variadic`
-
-Methods with the `abstract` feature may only be members of `abstract` classes or
-[interfaces], and all methods that are members of [interfaces] must be
-`abstract`.
-
-Methods that are `static` cannot feature the `overrides` attribute, as `static`
-members are not inherited.
-
-#### Properties
-
-Attribute | Type | Description
--------------|---------------|--------------------------------------------------
-`abstract` |`boolean` |Whether this property is `abstract`
-`const` |`boolean` |Whether this property is a constant (implies `static` and `immutable`)
-`immutable` |`boolean` |Whether this property is immutable
-`name` |`string` |The name of the property
-`optional` |`boolean` |Whether this property is optional
-`overrides` |`string` |The fully-qualified name of the class/interface that declares the overridden property
-`protected` |`boolean` |Whether this constructor is protected
-`static` |`boolean` |Whether this property is `static`
-`type` |`TypeReference`|The type of the property
-
-Properties that are `const` must have a `name` that is `UPPER_SNAKE_CASED`. They
-represent constants similar to [Enum Members], which can be proactively resolved
-by the `jsii` runtimes.
-
-Properties that are `static` cannot feature the `overrides` attribute, as
-`static` members are not inherited.
diff --git a/docs/handbooks/language-implementation.md b/docs/handbooks/language-implementation.md
deleted file mode 100644
index 931ab54f7d..0000000000
--- a/docs/handbooks/language-implementation.md
+++ /dev/null
@@ -1,217 +0,0 @@
-# Language Implementation Handbook
-
-This handbook provides an overview of the process that should be followed when
-looking to implement support for a new programming language in *jsii*. It
-attempts to provide a step-by-step procedure, while drawing the reader's
-attention on points that have been found to cause problems in the past.
-
-__Table of Contents__
-1. [Foreword](#foreword)
-1. [Scoping & Planning](#scoping-&-planning)
- 1. [Language Proposition RFC](#language-proposition-rfc)
-1. [Code Generation](#code-generation)
-1. [Host Library](#host-library)
-1. [Building & Packaging](#building-&-packaging)
-1. [Documentation](#documentation)
-1. [Developer Preview](#developer-preview)
-1. [General Availability](#general-availability)
-
---------------------------------------------------------------------------------
-
-## Foreword
-
-Implementing a new language in *jsii* is not just a matter of implementing code
-generation. Mapping the *[jsii type system]* to a new programming language means
-finding how to represent an API originally designed in TypeScript to a form that
-is as idiomatic as possible in the new language. This is a craft that often
-requires trial and error, and the best (if not only) way to validate a proposal
-is to put it in front of users and seek feedback. As a consequence, this
-endeavor should be expected to span months, not weeks.
-
-
-## Scoping & Planning
-
-The first step of most successful projects is to start by scoping work out and
-establishing a baseline plan to execute on. For contributors not yet familiar
-with *jsii*, the [specification] document is a great place to start. In
-particular, the [New Language Intake] document provides a high-level view of the
-recommended process for implementing new language support.
-
-The work of implementing support for a new language involves many different
-components:
-- The [`jsii`] compiler emits warnings when a language's reserved words are used
- to name types, methods or properties; as this will later require slugification
- or escaping in the generated code - usually resulting in a degraded developer
- experience.
-- The [`jsii-pacmak`] tool includes code generators for all supported languages,
- and a new implementation must be provided for the new language.
-- Code generation usually requires specific configuration to be provided in
- order to be able to generate valid packages (for example, the **Java** code
- generator requires a base java package to generate into, as well as a Maven
- group and artifact ID for the package). The [`jsii-config`] tool needs to be
- updated with support generating a configuration block with the required
- entries for the new code generator.
-- [`jsii-rosetta`] tool translates **TypeScript** example code found in the
- original documentation into the new target language. A new translation
- implementation needs to be added for the new language.
-- Building and publishing infrastructure elements are provided by
- [`aws-delivlib`] to make it easier for *jsii* users to publish their libraries
- to all supported package registries.
-
-### Language Proposition RFC
-
-The recommended way to formalize the initial plan is to write it into an RFC
-hosted in the [CDK RFC repository]. Enough time has to be spent considering the
-requirements in order to get the work scoped and planned well, ensuring smooth
-execution.
-
-An additional benefit of following the RFC process is that it makes it easier
-to track learnings accumulated through the implementation process, as those will
-be tracked as comments or iterations on the RFC document.
-
-It is possible (and sometimes desirable) to start prototyping code-generation
-for the new language, as this can highlight implementation challenges that need
-to be discussed in the RFC document. In any case, examples of the API signatures
-that are expected to be rendered allow early feedback to be provided by possible
-future users, and still helps identify challenges.
-
-The following questions should be answered as early as possible in the process,
-to avoid surprises later on that result in significant re-engineering effort:
-
-* What do the generated APIs look like, for the typical API idioms?
- - *Classes* (constructors, properties, methods, inheritance strategy, abstract
- members, ...)
- + The [AWS CDK] (one of the main consumers of *jsii*) uses specific patterns
- to offer a better experience in many programming languages. For example,
- constructor signatures where the last argument is a *jsii struct* allows
- for keyword argument lifting in **Python**, and convenient `Builder` APIs
- in **Java**.
- - *Enums*
- - *Interfaces* and *Structs* (properties, methods, inheritance strategy,
- implementation, ...). In particular, how are new optional properties handled
- (those are not considered breaking change within the [jsii type system]).
- - *Structs* (properties, inheritance strategy, implementation, ...)
-* What information is needed in order for the code-generator to produce
- artifacts? What should the configuration block look like?
-* What is the standard way to publish packages for the new language?
- - Are there any requirements (code signature, special metadata, ...) that need
- to be implemented in order to publish valid packages?
- - How are dependencies modeled? If [semantic versioning] is not the norm,
- what is the strategy to correctly represent semantic version ranges?
-* What are the toolchain and platform requirements?
- - For example, **Java** requires an OpenJDK 8 distribution and `maven`,
- **Python** requires `python` 3.6 or above, etc...
-
-## Code Generation
-
-First, implement a first version of the code generation for the new language
-before getting too far into the *[host library](#host-library)* implementation.
-This top-down approach ensures the requirements for the lower level parts of
-the implementation are well-defined before they are implemented (reducing the
-chances that significant re-work has to be done), and enables using the [Standard
-Compliance Suite] to ensure the overall implementation is *correct* according
-to the [specification] (since the code necessary to implement the test cases
-will be available right from the start).
-
-This work happens within the [`jsii-pacmak`] package.
-
-Focus initially on the API signatures before getting into their implementation.
-The first version may even throw a *not implemented* exception when called.
-
-The [`jsii-calc`] package, can be used as a sample consuming library which uses
-*jsii* to generate code in all target languages. Start by making sure a decent
-API is generated from this package and its dependencies, and use those to
-implement the tests from the [Standard Compliance Suite]. You'll also get a
-feeling for whether the generated code achieves a good developer experience or
-not.
-
-## Host Library
-
-Now that we are generating "empty shell" APIs that represent the necessary
-entities to back the [Standard Compliance Suite] tests, start implementing the
-*host library* and update the code generator until all the tests pass. It is
-possible to publish artifacts even when tests in the suite are failing. As soon
-as basic features are working, work on [Building and
-Packaging](#building-and-packaging) can start, so early feedback can be
-gathered.
-
-> :construction: A standard architecture for the *host library* has not been
-> documented yet. Upcoming language implementations should contribute to this
-> process by documenting a general architecture that should be implementable
-> in any programming languages (and thus, abstracting away language
-> specificities).
-
-## Building & Packaging
-
-The necessary toolchains should be added to he [`jsii/superchain`] Docker image,
-so that the [`jsii-pacmak`] generation can be changed to support building ready
-to publish artifacts instead of just code.
-
-Before publishing any artifacts, ensure all packages (the *host library* as well
-as generated artifacts) are designated as *experimental* (e.g: **Python**
-packages were annotated with the `Development Status :: 4 - Beta` trove
-classifier on PyPI, and **NuGet** packages were published with a pre-release
-version such as `1.2.3-pre`).
-
-Additionally, [`aws-delivlib`] needs to be augmented to support publishing
-artifacts to the language's package repository.
-
-> :construction: The package publishing is being extracted from [`aws-delivlib`]
-> into a standalone library, currently hosted at
-> [`eladb/jsii-release`](https://github.com/eladb/jsii-release).
-
-## Documentation
-
-Before releasing the new language support to *Developer Preview*, basic
-documentation needs to be produced to explain how to configure a *jsii* project
-to support the new language, and any peculiarities in working with libraries
-generated by [`jsii-pacmak`] for this language.
-
-Support for example code translation should also be built into [`jsii-rosetta`].
-
-## Developer Preview
-
-Once the full [Standard Compliance Suite] passes (possibly with the exception of
-certain fringy features), and the documentation covering all aspects of using
-the language bindings have been produced, the new language can be released to
-*Developer Preview*.
-
-It is recommended that new languages stay in *Developer Preview* for a minimum
-of 4 weeks, ideally until they have received sufficient usage to have built
-confidence that there are no major usability concerns: once out of *Developer
-Preview*, it will no longer be possible to introduce breaking changes to the
-generated code in order to address usability issues or bugs.
-
-In order to improve the chances of catching usability issues, focused user
-experience studies will be conducted with an audience composed of developers
-with varied degrees of experience with the new language.
-
-> :construction: A user experience template will be provided to ensure coverage
-> of critical aspects of the experience. Any critical user experience issue
-> (for example, issues that required breaking changes to the generated code)
-> discovered but not covered in the template should be added to the template so
-> that subsequent language implementations do not fall to the same problem.
-
-## General Availability
-
-Once the new language has been in *Developer Preview* without any significant
-usability issues or bugs for a sufficient amount of time and is used in
-real-world use-cases such as for [AWS CDK] applications, it becomes a candidate
-to be declared *Generally Available*. At this point, breaking changes are no
-longer possible on the generated code.
-
-
-[jsii type system]: ../specifications/2-type-system.md
-[specification]: ../specifications/1-introduction.md
-[New Language Intake]: ../specifications/5-new-language-intake.md
-[CDK RFC repository]: https://github.com/awslabs/aws-cdk-rfcs#readme
-[`jsii`]: ../../packages/jsii
-[`jsii-calc`]: ../../packages/jsii-calc
-[`jsii-config`]: ../../packages/jsii-config
-[`jsii-pacmak`]: ../../packages/jsii-pacmak
-[`jsii-rosetta`]: ../../packages/jsii-rosetta
-[Standard Compliance Suite]: ../specifications/4-standard-compliance-suite.md
-[`jsii/superchain`]: ../../superchain
-[`aws-delivlib`]: https://github.com/awslabs/aws-delivlib
-[AWS CDK]: https://github.com/aws/aws-cdk
-[semantic versioning]: https://semver.org
diff --git a/docs/specifications/1-introduction.md b/docs/specifications/1-introduction.md
deleted file mode 100644
index b43133de1c..0000000000
--- a/docs/specifications/1-introduction.md
+++ /dev/null
@@ -1,210 +0,0 @@
-# Introduction
-
-This document provides a high level overview of *jsii*, starting with its
-design tenets. It introduces the concepts and components that compose *jsii*.
-
-
-## Updating the Specification
-
-### Introduction
-
-The *jsii* specification follows the guiding principles of an RFC. It is a
-living document that describes the current understanding of how the various
-[components](#components) of *jsii* are operating, as well as the approaches
-used to ensure consistent behavior across the various supported languages.
-
-The document is hosted with the *jsii* codebase, making it easy to determine
-what specification was in place at the time of a give *jsii* release (by ways of
-referring to the `vX.Y.Z` git tag). A single version of the specification is
-considered **active** at any given time: the version of the specification that
-is represented on the `HEAD` commit of the `main` branch of the [`aws/jsii`]
-repository. The **active** specification must be the base version for any update
-proposal.
-
-[`aws/jsii`]: https://github.com/aws/jsii
-
-The process to update the specification is intended to be as lightweight as
-possible, while ensuring sufficient conversation takes place before implementing
-significant (and breaking) changes. Since the process to update the
-specification is part of the specification itself, it is amenable to be changed
-following the process described in the currently **active** specification.
-
-### Process
-
-While the general process for updating the specification is to create a GitHub
-pull request against the [`aws/jsii`] repository, the exact requirements for
-what should be included in the pull request vary depending on the type of update
-that is proposed:
-
-- [:warning: Changing Behavior](#new-behavior) describes the process to be
- followed when introducing changes to the behavior of any component of *jsii*:
- new features, breaking changes to existing features, ...
-- [:mag: Addressing Gaps](#addressing-gaps) is the process used for adding
- specification around existing but unspecified behavior.
-- [:thumbsup: Trivial Changes](#trivial) explains how to propose changes that
- improve the specification without changing its meaning.
-
-#### 
