Yuhsuan/documentation

.github/workflows/continuous_integration.yml

@@ -13,6 +13,39 @@ jobs:
       - run: npm install --legacy-peer-deps
       - run: npm run checkformat
 
+  doc-format-check:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs_website
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+      - run: npm ci
+      - run: npm run checkformat
+
+  test-doc:
+    name: Test deployment of the documentation website
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs_website
+    needs: doc-format-check
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Test build website
+        run: npm run build
+
   node-v16:
     runs-on: [self-hosted, Linux, X64, Docker]
     needs: format-check

.github/workflows/deploy.yml

@@ -0,0 +1,30 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - dev
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs_website
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+
+      - name: Install dependencies
+        run: npm install
+      - name: Build website
+        run: npm run build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build

README.md

@@ -103,8 +103,10 @@ npm install
 WebAssembly libraries can be built with `npm run build-libs`.
 Additional build steps (building WebAssembly wrappers, protocol buffer modules and compiling the Typescript code) are performed by `npm run build`. This produces a production build in the `build` folder.
 
-To run a development build server, simply run `npm run start`. 
+To run a development build server, simply run `npm run start`.
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3377984.svg)](https://doi.org/10.5281/zenodo.3377984)
+## Developer documentation
 
+Automatically generated documentation can be found at [cartavis.org/carta-frontend](https://cartavis.org/carta-frontend/).
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3377984.svg)](https://doi.org/10.5281/zenodo.3377984)

docs_website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs_website/api/api.md

@@ -0,0 +1,10 @@
+## Table of Contents
+
+-   [<h4>Components</h4>](api/.-components)
+    -   [<h5>Components - Dialogs</h5>](api/.-components/Dialogs)
+    -   [<h5>Components - Shared</h5>](api/.-components/Shared)
+-   [<h4>Models</h4>](api/.-models)
+-   [<h4>Services</h4>](api/.-services)
+-   [<h4>Stores</h4>](api/.-stores)
+-   [<h4>Utilities</h4>](api/.-utilities)
+-   [<h4>Changelog</h4>](api/changelog)

docs_website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    presets: [require.resolve("@docusaurus/core/lib/babel/preset")]
+};

docs_website/docs/code-snippet-tutorial/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Code snippet tutorial",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "description": "Tutorials for the code snippet feature in CARTA frontend."
+    }
+}

docs_website/docs/code-snippet-tutorial/basics.md

@@ -0,0 +1,97 @@
+---
+sidebar_position: 2
+---
+
+# Basics
+
+Code snippets are regular ES6-based JavaScript (JS) code blocks.
+
+Lines starting with "//" are treated as comments. You can also comment in multiple lines using C-style comments.
+
+```javascript
+// Lines starting with "//" are treated as comments.
+/* you can also comment in
+ * multiple lines using C-style comments
+ */
+```
+
+To log to the development console, use `console.log`.
+
+```javascript
+console.log("hello world");
+```
+
+Variables can be defined using `let` (mutable) or `const` (immutable).
+
+```javascript
+let x = 1;
+const y = "hello world";
+x += 15;
+```
+
+## Functions
+
+Functions can be defined in a number of ways.
+
+```javascript
+function squared(x) {
+    return x * x;
+}
+
+// This is an arrow function
+const cubed = x => x * x * x;
+
+// This is an arrow function with a block of codes
+const sqrt = x => {
+    // You can use builtin JS library functions
+    return Math.sqrt(x);
+};
+```
+
+Functions can also be asynchronous. Any functions that wait for user input or interact with the backend will be asynchronous.
+
+```javascript
+function delay(time) {
+    return new Promise((resolve, reject) => {
+        if (time < 0) {
+            reject("Invalid delay duration");
+        } else {
+            setTimeout(resolve, time);
+        }
+    });
+}
+```
+
+You can `await` asynchronous functions within another async function, or at the top level.
+
+```javascript
+async function pauseForOneSecond() {
+    await delay(1000);
+    return true;
+}
+```
+
+Awaiting is necessary to ensure that return values can be used correctly. Compare the following outputs:
+
+```javascript
+console.log("Awaiting properly:");
+const resultWithAwait = await pauseForOneSecond();
+console.log(resultWithAwait);
+console.log();
+
+console.log("No await:");
+const resultWithoutAwait = pauseForOneSecond();
+console.log(resultWithoutAwait);
+console.log();
+```
+
+Asynchronous functions can also be used with promise syntax.
+
+```javascript
+delay(100).then(() => console.log("Looks promising"));
+delay(-100).catch(err => console.log(err));
+```
+
+Note that the response to the first "delay" call is printed after the second one, because execution is non-blocking.
+
+For more usages of ES6-based JavaScript, please refer to the features of the language.

docs_website/docs/code-snippet-tutorial/image-fitting.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 7
+---
+
+# Image fitting
+
+The process of fitting images with multiple Gaussians can be done using code snippets.
+
+The configuration for the fitting is accessible via [`ImageFittingStore`](/api/.-stores/class/ImageFittingStore). Example code:
+
+```javascript
+// Open an image
+const file = await app.openFile("[filename]");
+
+// Display the fitting widget
+app.dialogStore.showFittingDialog();
+
+// Clear previous inputs of initial values
+app.imageFittingStore.clearComponents();
+
+// Set initial values
+app.imageFittingStore.setComponents(2);
+
+const component1 = app.imageFittingStore.components[0];
+component1.setCenterX(128);
+component1.setCenterY(129);
+component1.setAmplitude(0.01);
+component1.setFwhmX(10);
+component1.setFwhmY(6);
+component1.setPa(36);
+
+const component2 = app.imageFittingStore.components[1];
+component2.setCenterX(135);
+component2.setCenterY(135);
+component2.setAmplitude(0.01);
+component2.setFwhmX(4);
+component2.setFwhmY(9);
+component2.setPa(40);
+
+// Fit the image
+app.imageFittingStore.fitImage();
+```

docs_website/docs/code-snippet-tutorial/image-properties.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 3
+---
+
+# Image properties
+
+Actions for modifying various properties of the image. In the following examples, we assume that an image is loaded as
+
+```javascript
+const file = await app.openFile("my_image.fits");
+```
+
+## Changing field of view
+
+The field of view can be adjusted using various functions within [`FrameStore`](/api/.-stores/class/FrameStore).
+
+[`setCenter`](/api/.-stores/class/FrameStore/#setCenter) and [`setCenterWcs`](/api/.-stores/class/FrameStore/#setCenterWcs) set the center of the image.
+
+```javascript
+// image coordinate
+file.setCenter([x position], [y position]);
+
+// world coordinate
+file.setCenterWcs("[x position, ex: 0:00:00.0615838925]", "[y position, ex: 29:59:59.1999990820]");
+```
+
+[`fitZoom`](/api/.-stores/class/FrameStore/#fitZoom) zooms the image to fit the widget size.
+
+```javascript
+file.fitZoom();
+```
+
+[`zoomToSize...`](/api/.-stores/class/FrameStore/#zoomToSizeX) functions zoom the image to a specific scale.
+
+```javascript
+// image coordinate
+file.zoomToSizeX([size in x direction]);
+file.zoomToSizeY([size in y direction]);
+
+// world coordinate
+file.zoomToSizeXWcs('[size in x direction, ex: 2.56"]');
+file.zoomToSizeYWcs('[size in y direction, ex: 2.56"]');
+```
+
+## Changing the channel and Stokes
+
+[`setChannel`](/api/.-stores/class/FrameStore/#setChannel) changes the channel of the image.
+
+```javascript
+file.setChannel([channel]);
+```
+
+[`setStokes`](/api/.-stores/class/FrameStore/#setStokes) and [`setStokesByIndex`](/api/.-stores/class/FrameStore/#setStokesByIndex) change the stokes of the image using [`POLARIZATIONS`](/api/.-models/enum/POLARIZATIONS) enum or the index.
+
+```javascript
+file.setStokes(2); // Stokes Q
+file.setStokesByIndex(2); // The third polarization shown in the animator widget
+```
+
+## Changing render configuration
+
+Render configuration can be modified using [`renderConfig`](/api/.-stores/class/RenderConfigStore) within [`FrameStore`](/api/.-stores/class/FrameStore).
+
+[`setCustomScale`](/api/.-stores/class/RenderConfigStore/#setCustomScale) and [`setPercentileRank`](/api/.-stores/class/RenderConfigStore/#setPercentileRank) change the rendering range.
+
+```javascript
+file.renderConfig.setCustomScale([clip min], [clip max]);
+file.renderConfig.setPercentileRank(90); // Change to 90%
+```
+
+[`setScaling`](/api/.-stores/class/RenderConfigStore/#setScaling) changes the scaling functions using [`FrameScaling`](/api/.-stores/enum/FrameScaling) enum.
+
+```javascript
+file.renderConfig.setScaling(1); // Log
+```
+
+[`setColorMap`](/api/.-stores/class/RenderConfigStore/#setColorMap) changes the color map using options in [`COLOR_MAPS_ALL`](/api/.-stores/class/RenderConfigStore/#COLOR_MAPS_ALL) list, and [`setInverted`](/api/.-stores/class/RenderConfigStore/#setInverted) inverts the color map.
+
+```javascript
+file.renderConfig.setColorMap("gray");
+file.renderConfig.setInverted(true);
+```

docs_website/docs/code-snippet-tutorial/moment-images.md

@@ -0,0 +1,31 @@
+---
+sidebar_position: 5
+---
+
+# Moment images
+
+The process of generating moment images can be done using code snippets.
+
+The configuration for the generator is accessible via [`SpectralProfileWidgetStore`](/api/.-stores/class/SpectralProfileWidgetStore). Available moment types (as enum) can be found [here](https://carta-protobuf.readthedocs.io/en/latest/enums.html#moment). Example code:
+
+```javascript
+// Open an image
+const file = await app.openFile("[filename]");
+
+// Create a spectral profile settings widget
+app.widgetsStore.createFloatingSpectralProfilerWidget();
+app.widgetsStore.createFloatingSettingsWidget("", "spectral-profiler-0", "spectral-profiler");
+
+// Get the SpectralProfileWidgetStore object
+const spectralProfileWidget = app.widgetsStore.spectralProfileWidgets.get("spectral-profiler-0");
+
+// Navigate to the moments tab
+spectralProfileWidget.setSettingsTabId(3);
+
+// Modify the configuration using SpectralProfileWidgetStore
+spectralProfileWidget.clearSelectedMoments(); // remove default: integrated value of the spectrum
+spectralProfileWidget.selectMoment(0); // mean value of the spectrum
+
+// Generate a moment image
+spectralProfileWidget.requestMoment();
+```