diff --git a/contribute/development/api/index.md b/contribute/development/api/index.md new file mode 100644 index 0000000..a241e22 --- /dev/null +++ b/contribute/development/api/index.md @@ -0,0 +1,11 @@ +# OpenSpace API +OpenSpace provides APIs for interacting with a running OpenSpace instance from external applications or web-based user interfaces. This section currently focuses on the [JavaScript / TypeScript API](https://github.com/OpenSpace/openspace-api-js) for building custom web UIs and browser-based tools; Python bindings are available in the [Python API](https://github.com/OpenSpace/openspace-api-python). + +:::{toctree} +:maxdepth: 1 +:caption: JavaScript API + +topic +update-typescript-types +test-and-publish-openspace-api-js +::: diff --git a/contribute/development/api/test-and-publish-openspace-api-js.md b/contribute/development/api/test-and-publish-openspace-api-js.md new file mode 100644 index 0000000..973211c --- /dev/null +++ b/contribute/development/api/test-and-publish-openspace-api-js.md @@ -0,0 +1,46 @@ +# Testing and Publishing Changes to `openspace-api-js` +This guide explains how to test local changes to [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js) in a consuming repository, such as the [WebGui](https://github.com/OpenSpace/OpenSpace-WebGui). It also explains how to publish those changes as prereleases or stable releases using `npm`. + +These steps apply to any package change, including newly generated types, new Topics, updated Lua library functions, and bug fixes. + +## 1. Test local changes in a consuming repository +1. In the `openspace-api-js` repository, run `npm pack`. This creates a tarball, e.g., `openspace-api-js-x.x.x.tgz`. +1. In the consuming repository, run `npm install ` to install it as a local dependency pointing at your build. + +## 2. Publish a prerelease package for testing +1. Bump to a prerelease version: + - For a new prerelease, set an explicit version: + ```sh + npm version x.x.x-dev.0 --no-git-tag-version + ``` + `--no-git-tag-version` avoids immediately committing the version bump. + - To iterate on an existing prerelease (e.g., new Lua definitions, a new Topic), bump the prerelease number instead of jumping to a new patch/minor/major version: + ```sh + npm version prerelease --preid=dev --no-git-tag-version + ``` + This bumps, for example, `1.0.3-dev.0` to `1.0.3-dev.1`. +1. Publish under the `dev` tag: + ```sh + npm publish --tag dev + ``` + This ensures the prerelease is not installed by a plain `npm install openspace-api-js`. +1. Consumers can install it with `npm install openspace-api-js@dev`, or a specific version with `npm install openspace-api-js@1.0.3-dev.0`. + +## 3. Upgrade from a prerelease to a stable release +When ready to promote a prerelease to a stable release, run: +```sh +npm version 1.0.3 --no-git-tag-version +npm publish +``` + +If you instead want to change which already-published *stable* version installs by default (without publishing again), repoint the `latest` dist-tag to that stable version, for example: +```sh +npm dist-tag add openspace-api-js@1.0.3 latest +``` +Note that this only changes what `npm install openspace-api-js` resolves to. It does not turn a prerelease into a stable release. + +:::{note} +**Versioning:** version numbers follow [semantic versioning](https://semver.org/), `major.minor.patch` (e.g., `1.0.3`). Use `npm version patch`, `npm version minor`, or `npm version major` for stable releases depending on the scope of the change. This bumps the corresponding version number by 1. For `-dev` builds, use the prerelease commands above. + +Again use `--no-git-tag-version` to avoid automatically committing the change. +::: diff --git a/contribute/development/api/topic.md b/contribute/development/api/topic.md new file mode 100644 index 0000000..04168ef --- /dev/null +++ b/contribute/development/api/topic.md @@ -0,0 +1,15 @@ +# Creating a new OpenSpace Topic +This guide explains what a Topic is and how to create one: writing a schema and registering it in the engine. Once a Topic is created, see [Update TypeScript types from OpenSpace build](./update-typescript-types.md) for how to generate and publish the corresponding TypeScript types in [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js) so consuming repositories (for example, the [WebGui](https://github.com/OpenSpace/OpenSpace-WebGui)) can use them. + +## What is a Topic? +@TODO: Add a short explanation of what a Topic is, how it fits the OpenSpace API, our philosophy of using Lua functions, vs Topics, vs Events. Do we also want to include a link or something to our existing Topics? + +## Create a new Topic +1. Add the code for the topic in the OpenSpace engine, under e.g., `src/topic/` +1. Write a schema for the Topic (see [Writing a JSON Schema](https://github.com/OpenSpace/OpenSpace/tree/master/support/types#writing-a-json-schema) for a detailed how-to guide) +1. Register the Topic in the engine + 1. Register the Topic class in `src/topic/server.cpp` with a unique ID, e.g., `propertyTree` + 1. Add the schema to `registerCoreSchemas` in `core_registration.cpp` + +## Using the Topic +The Topic is used via the [JavaScript](https://github.com/OpenSpace/openspace-api-js) or [Python](https://github.com/OpenSpace/openspace-api-python) APIs. Use the same ID registered in step 3 above to start the Topic. diff --git a/contribute/development/api/update-typescript-types.md b/contribute/development/api/update-typescript-types.md new file mode 100644 index 0000000..b7f1c4d --- /dev/null +++ b/contribute/development/api/update-typescript-types.md @@ -0,0 +1,25 @@ +# Update TypeScript types from OpenSpace build +The [JavaScript API](https://github.com/OpenSpace/openspace-api-js) supports TypeScript types that are generated from JSON schemas. The npm package [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js) ships with pre-generated types targeting a specific OpenSpace version. These types need to be updated regularly, for example, when a Topic's schema changes, a new Topic is added, or the Lua API is updated. + +This guide walks through generating the corresponding TypeScript types in `openspace-api-js` from an OpenSpace build, and trying them out in a consuming repository (for example, the [WebGui](https://github.com/OpenSpace/OpenSpace-WebGui)). + +## 1. Generate the updated JSON schemas +If a Topic's schema has changed, it needs to be regenerated. Run OpenSpace's `DocsWriter`. This writes all JSON schemas into `/support/types`. +:::{note} +Skip this step unless you've changed a Topic's schema. +::: + +## 2. Generate the TypeScript types +There are two kinds of types that can be generated for the API: + + - [Topic types](https://github.com/OpenSpace/openspace-api-js#topic-types-generate-topic-types), based on the JSON schemas generated in step 1. + - [Lua API types](https://github.com/OpenSpace/openspace-api-js#lua-library-types-generate-lua-library), based on the Lua functions available in the OpenSpace build. + +See the `openspace-api-js` guide's [Generating types from your OpenSpace build](https://github.com/OpenSpace/openspace-api-js#generating-types-from-your-openspace-build) section for detailed information about the required prerequisites and exact commands for the generation of both Topic and Lua API types. The generated types are written into the `openspace-api-js` repository. + +## 3. Test local changes in a consuming repository +1. In the `openspace-api-js` repository, run `npm pack`. This creates a tarball, e.g. `openspace-api-js-x.x.x.tgz`. +1. In the consuming repository, run `npm install ` to install it as a local dependency pointing at your build. + +## 4. Publish the updated package +See the [detailed steps](./test-and-publish-openspace-api-js.md) on how to publish the updated `openspace-api-js` package. diff --git a/contribute/development/index.md b/contribute/development/index.md index 65b0390..df6bfb9 100644 --- a/contribute/development/index.md +++ b/contribute/development/index.md @@ -13,6 +13,7 @@ tools/index dependencies/index coding-style structure/index +api/index deploying-windows folder-layout opengl