From 740a20b2b6f85e8ba5d342d7a131fe39c9cdd02f Mon Sep 17 00:00:00 2001 From: Andreas Engberg Date: Mon, 7 Sep 2026 16:39:48 +0200 Subject: [PATCH 1/6] add pages how to publish api and create a new topic --- .../development/api/creating-a-new-topic.md | 30 +++++++++++++++ contribute/development/api/index.md | 10 +++++ .../api/test-and-publish-openspace-api-js.md | 37 +++++++++++++++++++ contribute/development/index.md | 1 + 4 files changed, 78 insertions(+) create mode 100644 contribute/development/api/creating-a-new-topic.md create mode 100644 contribute/development/api/index.md create mode 100644 contribute/development/api/test-and-publish-openspace-api-js.md diff --git a/contribute/development/api/creating-a-new-topic.md b/contribute/development/api/creating-a-new-topic.md new file mode 100644 index 0000000..3747661 --- /dev/null +++ b/contribute/development/api/creating-a-new-topic.md @@ -0,0 +1,30 @@ +# Creating a new OpenSpace Topic + +This guide walks through the full process of adding a new Topic to OpenSpace: registering it in the engine, generating the corresponding TypeScript types in [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js), and publishing those types so consuming repositories (e.g. the WebGUI) can use them. + +## 1. Create the Topic + +1. Write a schema for the new Topic. +1. See [Writing a JSON Schema](https://github.com/OpenSpace/OpenSpace/tree/master/support/types#writing-a-json-schema) for a detailed how-to guide. + +## 2. Register the Topic in the engine + +1. Register the Topic class in `server.cpp` with a unique id, e.g. `propertyTree`. +1. Add the schema to `registerCoreSchemas` in `core_registration.cpp`. + +## 3. Generate the updated JSON schemas + +1. Run OpenSpace's `DocsWriter`. This writes all JSON schemas into `/support/types`. + +## 4. Generate the TypeScript types + +1. Generate TypeScript types from the updated JSON schemas — see openspace-api-js's [Generating types from your OpenSpace build](https://github.com/OpenSpace/openspace-api-js#generating-types-from-your-openspace-build) section for the exact command and prerequisites. + +## 5. Try the new types 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. + +## 6. Publish the updated `openspace-api-js` package + +See the [detailed steps](./test-and-publish-openspace-api-js.md) on how to publish the updated npm package. diff --git a/contribute/development/api/index.md b/contribute/development/api/index.md new file mode 100644 index 0000000..56aea31 --- /dev/null +++ b/contribute/development/api/index.md @@ -0,0 +1,10 @@ +# OpenSpace API +OpenSpace provides two APIs for interacting with a running OpenSpace instance from external applications or web-based user interfaces. The [JavaScript / TypeScript API](https://github.com/openspace/openspace-api-js) is primarily intended for building custom web UIs and browser-based tools, while the [Python API](https://github.com/openspace/openspace-api-python) is suited for scripting, automation, and data-driven workflows. + +:::{toctree} +:maxdepth: 1 +:caption: JavaScript API + +creating-a-new-topic +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..c6e5425 --- /dev/null +++ b/contribute/development/api/test-and-publish-openspace-api-js.md @@ -0,0 +1,37 @@ +# Testing and Publishing `openspace-api-js` Changes + +This guide covers how to try out local changes to [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js) — such as newly generated types — in a consuming repository, and how to publish those changes as a prerelease or stable release. It applies to any change to the package (new Topics, updated Lua library functions, bug fixes, etc.), not just Topic creation. + +## 1. Try the new types 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 the updated package + +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`. +1. When ready to promote a prerelease to a stable release: + ```sh + npm version 1.0.3 --no-git-tag-version + npm publish + ``` + If the already-published prerelease build is good as-is, you can skip republishing and just repoint the tag: + ```sh + npm dist-tag add openspace-api-js@1.0.3-dev.0 latest + ``` 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 From a7eb2fd9689b72d07c00298a60ec5fcc506f6fdc Mon Sep 17 00:00:00 2001 From: Andreas Engberg Date: Mon, 7 Sep 2026 17:04:14 +0200 Subject: [PATCH 2/6] fix pr comment --- contribute/development/api/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contribute/development/api/index.md b/contribute/development/api/index.md index 56aea31..6d1edef 100644 --- a/contribute/development/api/index.md +++ b/contribute/development/api/index.md @@ -1,5 +1,5 @@ # OpenSpace API -OpenSpace provides two APIs for interacting with a running OpenSpace instance from external applications or web-based user interfaces. The [JavaScript / TypeScript API](https://github.com/openspace/openspace-api-js) is primarily intended for building custom web UIs and browser-based tools, while the [Python API](https://github.com/openspace/openspace-api-python) is suited for scripting, automation, and data-driven workflows. +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 From 2751996856dea7cbb7ee5e705f652bfc9f3f43c5 Mon Sep 17 00:00:00 2001 From: Andreas Engberg <48772850+engbergandreas@users.noreply.github.com> Date: Tue, 8 Sep 2026 13:12:27 +0200 Subject: [PATCH 3/6] Apply batched suggestions from code review Co-authored-by: Alexander Bock --- contribute/development/api/creating-a-new-topic.md | 7 ------- .../development/api/test-and-publish-openspace-api-js.md | 5 +---- 2 files changed, 1 insertion(+), 11 deletions(-) diff --git a/contribute/development/api/creating-a-new-topic.md b/contribute/development/api/creating-a-new-topic.md index 3747661..93b5830 100644 --- a/contribute/development/api/creating-a-new-topic.md +++ b/contribute/development/api/creating-a-new-topic.md @@ -1,30 +1,23 @@ # Creating a new OpenSpace Topic - This guide walks through the full process of adding a new Topic to OpenSpace: registering it in the engine, generating the corresponding TypeScript types in [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js), and publishing those types so consuming repositories (e.g. the WebGUI) can use them. ## 1. Create the Topic - 1. Write a schema for the new Topic. 1. See [Writing a JSON Schema](https://github.com/OpenSpace/OpenSpace/tree/master/support/types#writing-a-json-schema) for a detailed how-to guide. ## 2. Register the Topic in the engine - 1. Register the Topic class in `server.cpp` with a unique id, e.g. `propertyTree`. 1. Add the schema to `registerCoreSchemas` in `core_registration.cpp`. ## 3. Generate the updated JSON schemas - 1. Run OpenSpace's `DocsWriter`. This writes all JSON schemas into `/support/types`. ## 4. Generate the TypeScript types - 1. Generate TypeScript types from the updated JSON schemas — see openspace-api-js's [Generating types from your OpenSpace build](https://github.com/OpenSpace/openspace-api-js#generating-types-from-your-openspace-build) section for the exact command and prerequisites. ## 5. Try the new types 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. ## 6. Publish the updated `openspace-api-js` package - See the [detailed steps](./test-and-publish-openspace-api-js.md) on how to publish the updated npm package. diff --git a/contribute/development/api/test-and-publish-openspace-api-js.md b/contribute/development/api/test-and-publish-openspace-api-js.md index c6e5425..cad2137 100644 --- a/contribute/development/api/test-and-publish-openspace-api-js.md +++ b/contribute/development/api/test-and-publish-openspace-api-js.md @@ -1,14 +1,11 @@ # Testing and Publishing `openspace-api-js` Changes - -This guide covers how to try out local changes to [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js) — such as newly generated types — in a consuming repository, and how to publish those changes as a prerelease or stable release. It applies to any change to the package (new Topics, updated Lua library functions, bug fixes, etc.), not just Topic creation. +This guide covers how to try out local changes to [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js), such as newly generated types, in a consuming repository, and how to publish those changes as a prerelease or stable release. It applies to any change to the package (new Topics, updated Lua library functions, bug fixes, etc.), not just Topic creation. ## 1. Try the new types 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 the updated package - 1. Bump to a prerelease version: - For a new prerelease, set an explicit version: ```sh From 8be91ace4a26f0bd60b1c2df28c473da5a59cad0 Mon Sep 17 00:00:00 2001 From: Andreas Engberg Date: Wed, 9 Sep 2026 14:14:07 +0200 Subject: [PATCH 4/6] restructured pages --- .../development/api/creating-a-new-topic.md | 23 ----------- contribute/development/api/index.md | 3 +- .../api/test-and-publish-openspace-api-js.md | 40 ++++++++++++------- contribute/development/api/topic.md | 15 +++++++ .../api/update-typescript-types.md | 20 ++++++++++ 5 files changed, 62 insertions(+), 39 deletions(-) delete mode 100644 contribute/development/api/creating-a-new-topic.md create mode 100644 contribute/development/api/topic.md create mode 100644 contribute/development/api/update-typescript-types.md diff --git a/contribute/development/api/creating-a-new-topic.md b/contribute/development/api/creating-a-new-topic.md deleted file mode 100644 index 93b5830..0000000 --- a/contribute/development/api/creating-a-new-topic.md +++ /dev/null @@ -1,23 +0,0 @@ -# Creating a new OpenSpace Topic -This guide walks through the full process of adding a new Topic to OpenSpace: registering it in the engine, generating the corresponding TypeScript types in [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js), and publishing those types so consuming repositories (e.g. the WebGUI) can use them. - -## 1. Create the Topic -1. Write a schema for the new Topic. -1. See [Writing a JSON Schema](https://github.com/OpenSpace/OpenSpace/tree/master/support/types#writing-a-json-schema) for a detailed how-to guide. - -## 2. Register the Topic in the engine -1. Register the Topic class in `server.cpp` with a unique id, e.g. `propertyTree`. -1. Add the schema to `registerCoreSchemas` in `core_registration.cpp`. - -## 3. Generate the updated JSON schemas -1. Run OpenSpace's `DocsWriter`. This writes all JSON schemas into `/support/types`. - -## 4. Generate the TypeScript types -1. Generate TypeScript types from the updated JSON schemas — see openspace-api-js's [Generating types from your OpenSpace build](https://github.com/OpenSpace/openspace-api-js#generating-types-from-your-openspace-build) section for the exact command and prerequisites. - -## 5. Try the new types 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. - -## 6. Publish the updated `openspace-api-js` package -See the [detailed steps](./test-and-publish-openspace-api-js.md) on how to publish the updated npm package. diff --git a/contribute/development/api/index.md b/contribute/development/api/index.md index 6d1edef..a241e22 100644 --- a/contribute/development/api/index.md +++ b/contribute/development/api/index.md @@ -5,6 +5,7 @@ OpenSpace provides APIs for interacting with a running OpenSpace instance from e :maxdepth: 1 :caption: JavaScript API -creating-a-new-topic +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 index cad2137..beca0b0 100644 --- a/contribute/development/api/test-and-publish-openspace-api-js.md +++ b/contribute/development/api/test-and-publish-openspace-api-js.md @@ -1,18 +1,18 @@ -# Testing and Publishing `openspace-api-js` Changes -This guide covers how to try out local changes to [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js), such as newly generated types, in a consuming repository, and how to publish those changes as a prerelease or stable release. It applies to any change to the package (new Topics, updated Lua library functions, bug fixes, etc.), not just Topic creation. +# Testing and Publishing Changes to `openspace-api-js` +This guide covers how to try out local changes to [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js), such as newly generated types, in a consuming repository (for example, the [WebGui](https://github.com/OpenSpace/OpenSpace-WebGui)), and how to publish those changes as a prerelease or stable release. It applies to any change to the package, for example, new Topics, updated Lua library functions, bug fixes, and other API changes. -## 1. Try the new types 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. 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 the updated package +## 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: + - 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 ``` @@ -23,12 +23,22 @@ This guide covers how to try out local changes to [`openspace-api-js`](https://g ``` 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`. -1. When ready to promote a prerelease to a stable release: - ```sh - npm version 1.0.3 --no-git-tag-version - npm publish - ``` - If the already-published prerelease build is good as-is, you can skip republishing and just repoint the tag: - ```sh - npm dist-tag add openspace-api-js@1.0.3-dev.0 latest - ``` + +## 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, and the prerelease commands above for `-dev` builds. This bumps the corresponding version number by 1. + +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..328decf --- /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? + +## 1. Create the Topic +Write a schema for the new 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). + +## 2. 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), use the same ID registered in step #2 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..2e84f33 --- /dev/null +++ b/contribute/development/api/update-typescript-types.md @@ -0,0 +1,20 @@ +# Update TypeScript types from OpenSpace build +The [JavaScript API](https://github.com/OpenSpace/openspace-api-js) supports TypeScript types which 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, whenever a Topic's schema is changed, adding a new Topic, or updating the Lua API. + +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 types that can be generated for the API: [Topic types](https://github.com/OpenSpace/openspace-api-js#topic-types-generate-topic-types) from updated JSON schemas and [Lua API types](https://github.com/OpenSpace/openspace-api-js#lua-library-types-generate-lua-library) from new or updated Lua functions. See `openspace-api-js`'s [Generating types from your OpenSpace build](https://github.com/OpenSpace/openspace-api-js#generating-types-from-your-openspace-build) section for the exact command and prerequisites. + +## 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. From e14cf12dc52b334db51c4433a48d044fbc36c6d6 Mon Sep 17 00:00:00 2001 From: Andreas Engberg Date: Wed, 9 Sep 2026 14:25:14 +0200 Subject: [PATCH 5/6] fix issues --- contribute/development/api/topic.md | 2 +- contribute/development/api/update-typescript-types.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/contribute/development/api/topic.md b/contribute/development/api/topic.md index 328decf..230a7a6 100644 --- a/contribute/development/api/topic.md +++ b/contribute/development/api/topic.md @@ -12,4 +12,4 @@ Write a schema for the new Topic (see [Writing a JSON Schema](https://github.com 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), use the same ID registered in step #2 to start 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 #2 to start the Topic. diff --git a/contribute/development/api/update-typescript-types.md b/contribute/development/api/update-typescript-types.md index 2e84f33..8350b7d 100644 --- a/contribute/development/api/update-typescript-types.md +++ b/contribute/development/api/update-typescript-types.md @@ -4,8 +4,8 @@ The [JavaScript API](https://github.com/OpenSpace/openspace-api-js) supports Typ 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) +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. ::: From 2c6bfbfa271036f5247f8a8ac2b1b7ed1f424389 Mon Sep 17 00:00:00 2001 From: Andreas Engberg <48772850+engbergandreas@users.noreply.github.com> Date: Wed, 9 Sep 2026 15:42:19 +0200 Subject: [PATCH 6/6] apply pr comments Co-authored-by: Emma Broman --- .../api/test-and-publish-openspace-api-js.md | 6 ++++-- contribute/development/api/topic.md | 16 ++++++++-------- .../development/api/update-typescript-types.md | 9 +++++++-- 3 files changed, 19 insertions(+), 12 deletions(-) diff --git a/contribute/development/api/test-and-publish-openspace-api-js.md b/contribute/development/api/test-and-publish-openspace-api-js.md index beca0b0..973211c 100644 --- a/contribute/development/api/test-and-publish-openspace-api-js.md +++ b/contribute/development/api/test-and-publish-openspace-api-js.md @@ -1,5 +1,7 @@ # Testing and Publishing Changes to `openspace-api-js` -This guide covers how to try out local changes to [`openspace-api-js`](https://github.com/OpenSpace/openspace-api-js), such as newly generated types, in a consuming repository (for example, the [WebGui](https://github.com/OpenSpace/OpenSpace-WebGui)), and how to publish those changes as a prerelease or stable release. It applies to any change to the package, for example, new Topics, updated Lua library functions, bug fixes, and other API changes. +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`. @@ -38,7 +40,7 @@ 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, and the prerelease commands above for `-dev` builds. This bumps the corresponding version number by 1. +**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 index 230a7a6..04168ef 100644 --- a/contribute/development/api/topic.md +++ b/contribute/development/api/topic.md @@ -2,14 +2,14 @@ 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? +@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? -## 1. Create the Topic -Write a schema for the new 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). - -## 2. 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`. +## 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 #2 to start 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 index 8350b7d..b7f1c4d 100644 --- a/contribute/development/api/update-typescript-types.md +++ b/contribute/development/api/update-typescript-types.md @@ -1,5 +1,5 @@ # Update TypeScript types from OpenSpace build -The [JavaScript API](https://github.com/OpenSpace/openspace-api-js) supports TypeScript types which 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, whenever a Topic's schema is changed, adding a new Topic, or updating the Lua API. +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)). @@ -10,7 +10,12 @@ Skip this step unless you've changed a Topic's schema. ::: ## 2. Generate the TypeScript types -There are two types that can be generated for the API: [Topic types](https://github.com/OpenSpace/openspace-api-js#topic-types-generate-topic-types) from updated JSON schemas and [Lua API types](https://github.com/OpenSpace/openspace-api-js#lua-library-types-generate-lua-library) from new or updated Lua functions. See `openspace-api-js`'s [Generating types from your OpenSpace build](https://github.com/OpenSpace/openspace-api-js#generating-types-from-your-openspace-build) section for the exact command and prerequisites. +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`.