And update the metaschema to accommodate the `isOverlay` properties
added in #8338. Overlay enums, like other overlay members, are
implemented out-of-band by the declaring package. Code generators should
not generate declarations for overlay enums.
Add a new `IsOverlay` option to schema types and functions that allows providers to document overlays in the schema. This makes it easier to generate API docs consistently, even for code that is generated outside of the typical codegen process.
These changes add a page to the developer docs that describes the design
and implementation of the `import` resource option and the `pulumi
import` command.
Co-authored-by: Levi Blackstone <levi@pulumi.com>
Just what it says on the tin: add some initial documentation for the
abstract Pulumi type system. Over time, this documentation will be
fleshed out to describe the relationship between the abstract type
system and its wire representations, Pulumi package schemas, and
language SDK implementations.
Co-authored-by: Andrew Fitzgerald <131809+fitzoh@users.noreply.github.com>
Co-authored-by: Ian Wahbe <ian@wahbe.com>
This schema can be used to validate the contents of a Pulumi deployment.
If a deployment validates against this schema, it should be considered
syntactically valid, though it may contain certain classes of semantic
errors (e.g. references to unknown resources in dependency lists,
dependency cycles, etc.).
This schema is not yet used for validation in practice and may not be
entirely accurate.
These changes also add this schema (and the schemas on which it depends)
to the developer documentation. jsonschema2md.go has been updated to
support multi-file schemas.
The Pulumi Package metaschema is a JSON schema definition that describes
the format of a Pulumi Package schema. The metaschema can be used to
validate certain basic properties of a Pulumi Package schema, including
(but not limited to):
- data types (e.g. is this property a string?)
- data formats (e.g. is this string property a valid regex?)
- object shapes (e.g. is this object missing required properties?)
The schema binder has been updated to use the metaschema as its first
validation pass.
In addition to its use in the binder, the metaschema has its own page in
the developer documentation. This page is generated using a small tool,
jsonschema2md.go.
- Add links within the resource registration docs
- Add a broad-strokes architectural diagram to the overview
- Add a `clean` target to the Makefile
- Expand the "Building" docs a bit
Developer documentation is written in Markdown and can be built into
HTML, PDF, etc. using Sphinx. Diagrams are written in PlantUML and
rendered as SVGs. All developer docs live in the `developer-docs` folder
under the root of the repository.
