Add pages: how to publish JS API and create a new topic

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
+:::

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 <path-to-openspace-api-js-x.x.x.tgz>` 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.
+:::

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.

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 `<OpenSpace>/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 <path-to-openspace-api-js-x.x.x.tgz>` 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.

contribute/development/index.md

@@ -13,6 +13,7 @@ tools/index
 dependencies/index
 coding-style
 structure/index
+api/index
 deploying-windows
 folder-layout
 opengl