📝 Add some content

astro.config.mjs

@@ -22,12 +22,17 @@ export default defineConfig({
       },
       sidebar: [
         {
-          label: 'Getting Started',
-          autogenerate: { directory: 'getting-started' },
+          label: 'Usage Guide',
+          items: ['usage/intro', 'usage/citing', 'usage/migration-guide'],
         },
         {
-          label: 'Getting Involved',
-          autogenerate: { directory: 'getting-involved' },
+          label: 'Development',
+          items: [
+            'development/architecture',
+            'development/contribution-guide',
+            'development/continuous-integration',
+            'development/release-management',
+          ],
         },
         {
           label: 'Plugins',

src/content/docs/development/architecture.mdx

@@ -0,0 +1,19 @@
+---
+title: Architecture
+description: The architecture of CosmoScout VR.
+tableOfContents: false
+---
+
+The high-level architecture of CosmoScout VR is shown in the diagram below.
+More fine-grained information on the specific plugins is available in the documentation of each plugin.
+
+![CosmoScout VR Architecture](/src/assets/architecture.svg)
+
+As a user, you will get in touch with the `cosmoscout` executable and the individual plugin libraries.
+While the plugins may link to some special-purpose third-party libraries, all of them link against the CosmoScout VR core libraries.
+
+There are five core libraries: [`cs-core`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-core) contains all the application logic and links against [`cs-graphics`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-graphics), [`cs-gui`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-gui) and [`cs-scene`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-scene).
+All of them use some utility functionality from [`cs-utils`](https://github.com/cosmoscout/cosmoscout-vr/tree/main/src/cs-utils).
+
+CosmoScout VR uses [several third-party libraries](https://github.com/cosmoscout/cosmoscout-vr/blob/main/docs/dependencies.md) as a basis.
+The most important ones are [ViSTA](https://github.com/cosmoscout/vista) (which itself requires [OpenSG 1.8](https://github.com/cosmoscout/opensg-1.8)) and [SPICE](https://naif.jpl.nasa.gov/naif/toolkit.html).

src/content/docs/development/continuous-integration.mdx

@@ -0,0 +1,66 @@
+---
+title: Continuous Integration
+description: Learn how CosmoScout VR uses Github Actions for continuous integration.
+---
+
+[Github Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) is used for continuous integration of CosmoScout VR.
+The file [`build.yml`](https://github.com/cosmoscout/cosmoscout-vr/blob/main/.github/workflows/build.yml) describes which jobs are run whenever a commit is pushed or a pull request is opened.
+
+## Clang-Format Check
+We enforce specific code formatting rules described in the file [`.clang-format`](https://github.com/cosmoscout/cosmoscout-vr/blob/main/.clang-format).
+For each and **every push event**, a job is executed which checks whether the code base obeys these rules.
+
+Commits passing this check will be marked with a ✔️, when the style does not match the rules, the commit will receive a ❌.
+
+## Comment Percentage Check
+For **pull requests only**, a job is run which analyses the amount of comments in the source tree.
+Therefore the percentage of source lines of code containing comments is calculated with the script [`cloc.sh`](https://github.com/cosmoscout/cosmoscout-vr/blob/main/tools/cloc.sh) and compared with the amount of comments in the base branch.
+
+This test will pass if the amount of comments did not decrease.
+
+## Builds of CosmoScout VR
+[Github Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) is also used to compile the code of CosmoScout VR and all of its dependencies.
+As this job takes quite some time, it is only executed for the events below:
+  * For each push to `main` if the commit message does not contain `[no-ci]`.
+  * For each push to any branch if commit message contains `[run-ci]`.
+  * For pull requests.
+
+The code is compiled on Ubuntu (with GCC and Clang) and on Windows (with MSVC).
+Tests are executed on all platforms and the results are uploaded to [coveralls.io](https://coveralls.io/github/cosmoscout/cosmoscout-vr).
+
+Both, the externals and CosmoScout's code itself is built with [ccache](https://ccache.dev/) and [clcache](https://github.com/frerich/clcache) in order to speed up build times by a factor of five.
+Between job runs, the object file cache is stored with the [cache action](https://github.com/actions/cache).
+
+## Unit Tests
+
+In CosmoScout VR, unit testing is done with [doctest](https://github.com/onqtam/doctest).
+Tests are executed for every build, so the same behavior of `[no-ci]` and `[run-ci]` as above applies here.
+There are two types of test cases, _regular_ tests and _graphical_ tests.
+
+### Regular Tests
+
+Regular tests require no OpenGL and no window.
+You can run them with the following scripts.
+
+#### Linux:
+
+```shell
+./install/linux-Release/bin/run_tests.sh
+```
+
+#### Windows:
+```batch
+install\windows-Release\bin\run_tests.bat
+```
+
+### Graphical Tests
+
+These tests require an OpenGL context and will open a window.
+Oftentimes they capture a screenshot and compare the result to a reference image.
+
+In order to make them possible even if there is no graphics card or display attached, they require [Xvfb](https://en.wikipedia.org/wiki/Xvfb) and [imagemagick](https://imagemagick.org/index.php) to be installed on your system.
+Graphical tests can only be executed on Linux for now:
+
+```shell
+./install/linux-Release/bin/run_graphical_tests.sh
+```

src/content/docs/development/contribution-guide.mdx

@@ -0,0 +1,113 @@
+---
+title: Write Code for CosmoScout VR
+description: Some guidelines for contributing to CosmoScout VR
+---
+
+Whenever you encounter a 🪲 **bug** or have 🎉 **feature request**, 
+report this via [Github issues](https://github.com/cosmoscout/cosmoscout-vr/issues).
+
+We are happy to receive contributions to CosmoScout VR in the form of **pull requests** via Github.
+Feel free to fork the repository, implement your changes and create a merge request to the `main` branch.
+There is a [forking guide](#forking-cosmoscout-vr) available to get you started!
+
+## Branching Guidelines
+
+New features and bug fixes are implemented in `feature/*` branches and are merged to `main` once they are finished.
+When a milestone is reached, a new tag is created.
+
+:::tip
+[Github Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) are used for continuous integration.
+All pull requests and pushes to `main` are built automatically.
+If you want to test a specific commit on any other branch, add **`[run-ci]`** to your commit message.
+:::
+
+## Coding Guidelines
+
+* Each header file should contain an include guard. For CosmoScout VR classes the naming scheme should be `CS_{NAMESPACE}_{FILNAME}_HPP` and for plugins it should be `CSP_{PLUGIN}_{FILNAME}_HPP`.
+* Class names should be written in CamelCase (e.g. `MyClass`).
+* Class methods should be written in small camelCase (e.g. `doSomething()`). 
+* Class members should start with a small `m` and continue in CamelCase (e.g. `mMyClassMember`). 
+* Apply clang-format before you create a merge request (either setup your IDE to do this or use the `clang-format.sh` script)
+* Never use `using namespace`.
+* Use features of modern C++11 / C++14 / C++17 (e.g. range-based for-loops, std::optional, std::variant, ...)!
+
+### Git Commit Messages
+
+Commits should start with a Capital letter and should be written in present tense (e.g. __:tada: Add cool new feature__ instead of __:tada: Added cool new feature__).
+It's a great idea to start the commit message with an applicable emoji. This does not only look great but also makes you rethink what to add to a commit.
+* 🎉 `:tada:` when when adding a cool new feature
+* 🔧 `:wrench:` when refactoring / improving a small piece of code
+* 🔨 `:hammer:` when refactoring / improving large parts of the code
+* ✨ `:sparkles:` when applying clang-format
+* 🎨 `:art:` improving / adding assets like textures or 3D-models
+* 🚀 `:rocket:` when improving performance
+* 📝 `:memo:` when writing docs
+* 🪲 `:beetle:` when fixing a bug
+* 💚 `:green_heart:` when fixing the CI build
+* ✔️ `:heavy_check_mark:` when working on tests
+* 🔼 `:arrow_up_small:` when adding / upgrading dependencies
+* 🔽 `:arrow_down_small:` when removing / downgrading dependencies
+* 🔀 `:twisted_rightwards_arrows:` when merging branches
+* 🔥 `:fire:` when removing files
+* 🚚 `:truck:` when moving / renaming files or namespaces
+
+:::tip
+A good way to enforce this on your side is to use a `commit-hook`. To do this, paste the following script into `.git/hooks/commit-msg`.
+
+```bash title=".git/hooks/commit-msg"
+#!/bin/bash
+
+# regex to validate in commit msg
+commit_regex='(:(tada|wrench|hammer|sparkles|art|rocket|memo|beetle|green_heart|arrow_up_small|arrow_down_small|twisted_rightwards_arrows|fire|truck|heavy_check_mark):(.+))'
+error_msg="Aborting commit. Your commit message is missing an emoji as described in CONTRIBUTING.md"
+
+if ! grep -xqE "$commit_regex" "$1"; then
+    echo "$error_msg" >&2
+    exit 1
+fi
+```
+
+And make sure that it is executable:
+
+``` bash
+chmod +x .git/hooks/commit-msg
+```
+:::
+
+# Forking CosmoScout VR
+
+This is pretty straight-forward. Just click the **Fork** button on the top right of this page. Then clone the forked repository, perform your changes, push to a feature branch and create a pull request to CosmoScout's `main` branch.
+
+``` bash
+git clone [email protected]:<your user name>/cosmoscout-vr.git
+cd cosmoscout-vr
+git remote add upstream [email protected]:cosmoscout/cosmoscout-vr.git
+git checkout main
+git submodule update --init --recursive
+git checkout -b feature/your-new-feature
+
+# ... do and commit your changes!
+
+git push origin feature/your-new-feature
+```
+
+When there were changes in CosmoScout's `main` branch, you will need to merge those to your fork before creating a pull request:
+
+``` bash
+git fetch upstream
+git merge upstream/main
+```
+
+Then you can create a pull request on GitHub to CosmoScout's `main` branch.
+
+## Creating a new plugin
+
+From a git-perspective, this is pretty straight-forward.
+All you need to do is creating a new directory in `plugins/`.
+For the beginning, you can copy the contents of another similar plugin to that directory.
+It will be picked up automatically by the build system.
+
+:::tip
+The new directory will also be ignored by git (due to the toplevel `.gitignore` file).
+That means that you can use a git repository for your plugin.
+:::

src/content/docs/development/release-management.mdx

@@ -0,0 +1,60 @@
+---
+title: Release Management
+description: How releases are managed in CosmoScout VR.
+tableOfContents: false
+---
+
+Releases are [published on GitHub](https://github.com/cosmoscout/cosmoscout-vr/releases).
+They are automatically created via [GitHub Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) whenever a git tag is pushed.
+The progress of future releases is tracked with [GitHub Milestones](https://github.com/cosmoscout/cosmoscout-vr/milestones).
+Submitted [issues](https://github.com/cosmoscout/cosmoscout-vr/issues) will be assigned to a specific release (depending on their importance and complexity).
+
+[GitHub Projects](https://github.com/cosmoscout/cosmoscout-vr/projects) will be used for high-level planning of complex features, such as network synchronization or photorealistic HDR rendering.
+
+## Version Numbers
+
+Releases in the 1.x.x series will most likely have a lot of breaking API changes, as the software becomes more and more mature.
+However, starting from version 2.0.0, version numbers of CosmoScout VR will be assigned according to the [Semantic Versioning](https://semver.org/) scheme.
+This means, given a version number MAJOR.MINOR.PATCH, we will increment the:
+
+1. MAJOR version when we make incompatible API changes,
+2. MINOR version when we add functionality in a backwards compatible manner, and
+3. PATCH version when we make backwards compatible bug fixes.
+
+## Creating Releases
+
+When a new version of CosmoScout VR is released, the following steps are performed.
+
+```bash
+git checkout main
+git submodule update --init --recursive
+```
+
+First, the [changelog.md](https://github.com/cosmoscout/cosmoscout-vr/blob/main/docs/changelog.md) has to be updated.
+Based on the commits since the last release and the completed milestone, a list of changes is compiled.
+When this is done, the file has to be comitted:
+
+```bash
+git add docs/changelog.md
+git commit -m ":memo: Update changelog.md"
+```
+
+Then edit the [project(... VERSION ...)](https://github.com/cosmoscout/cosmoscout-vr/blob/main/CMakeLists.txt#L8) in the main `CMakeLists.txt` file according to the new version number.
+Afterwards, the change has to be comitted:
+
+```bash
+git add CMakeLists.txt
+git commit -m ":tada: Bump version number"
+```
+
+Then we create a new git tag and push this state to the `main` branch.
+
+```bash
+git push origin main
+git tag v<new version number>
+git push origin v<new version number>
+```
+
+The default downloads for tags on GitHub do not contain git submodules.
+Therefore, a separate archive containing all the submodule code is automatically created via [GitHub Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) when a tag is pushed.
+Furthermore, binaries for Windows and Linux are automatically compiled with [GitHub Actions](https://github.com/cosmoscout/cosmoscout-vr/actions) and uploaded to the respective release.

src/content/docs/index.mdx

@@ -5,7 +5,7 @@ template: splash
 hero:
   actions:
     - text: Read the Documentation
-      link: /getting-started/intro/
+      link: /usage/intro/
       icon: right-arrow
     - text: Download from GitHub
       link: https://github.com/cosmoscout/cosmoscout-vr/releases

src/content/docs/usage/citing.mdx

@@ -0,0 +1,27 @@
+---
+title: Citing CosmoScout VR
+description: How to cite CosmoScout VR in your work.
+tableOfContents: false
+---
+
+If you use CosmoScout VR in your scientific work, please use the DOI of the version you are currently using.
+The DOI of each release is shown on the [releases page](https://github.com/cosmoscout/cosmoscout-vr/releases).
+
+:::tip
+With the link below you can export a citation in many different formats.
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3381953.svg)](https://doi.org/10.5281/zenodo.3381953)
+:::
+
+
+## Papers
+
+With the above DOI, you can cite the software itself. There are also a couple of related papers which you can refer to.
+
+> S. Schneegans, M. Zeumer, J. Gilg, and A. Gerndt, **"CosmoScout VR: A Modular 3D Solar System Based on SPICE"**, 2022 IEEE Aerospace Conference (AERO), 2022. https://doi.org/10.1109/AERO53065.2022.9843488
+
+> S. Schneegans, J. Gilg, V. Ahlers, and A. Gerndt, **"Real-Time Rendering of Eclipses without Incorporation of Atmospheric Effects"**, Computer Graphics Forum 41, 2022. https://doi.org/10.1111/cgf.14676
+
+> S. Schneegans, T. Meyran, I. Ginkel, G. Zachmann, and A. Gerndt, **"Physically Based Real-Time Rendering of Atmospheres using Mie Theory"**. Computer Graphics Forum 43, 2024. https://doi.org/10.1111/cgf.15010
+
+> J. Gilg, S. Zander, S. Schneegans, V. Ahlers, and A. Gerndt, "**Comparison of Depth Buffer Techniques for Large and Detailed 3D Scenes**", GI VR / AR Workshop, Gesellschaft für Informatik e.V., 2021. https://doi.org/10.18420/vrar2021_12
+

src/content/docs/usage/migration-guide.mdx

@@ -0,0 +1,64 @@
+---
+title: Migration Guide
+description: This guide helps you to migrate your existing CosmoScout VR configuration to a new version.
+---
+
+
+## Migrating from v1.2.0 to v1.3.0
+
+Some aspects of the scene configuration JSON file have changed in this version. Here are the changes you will have to apply to your existing configurations:
+
+* New required key `"resetDate"`: This should be either `"today"` or in the format `"1950-01-02 00:00:00.000"`. The simulation time will be set to this value when the reset button is clicked.
+* The initial observer position and rotation is now given in Cartesian coordinates: The observer property is now structured like this:
+  ```json
+  "observer": {
+    "center": "Earth",
+    "frame": "IAU_Earth",
+    "position": [0, 0, 25000000],
+    "rotation": [0, 0, 0, 1]
+  },
+  ```
+* `"events"` are now called `"bookmarks"` and structured like this:
+  ```json
+   "bookmarks": [
+    {
+      "name": "Mercury",
+      "icon": "mercury.png",
+      "location": {
+        "center": "Mercury",
+        "frame": "IAU_Mercury"
+      }
+    },
+    {
+      "name": "Apollo 17 Start",
+      "description": "Start of the Apollo 17 mission from the Kennedy Space Center.",
+      "color": [0.8, 0.8, 0.8],
+      "location": {
+        "center": "Earth",
+        "frame": "IAU_Earth",
+        "position": [-6717320.0, 3677613.0, 1137577.0],
+        "rotation": [0.154, 0.634, 0.182, -0.735]
+      },
+      "time": {
+        "start": "1972-12-07 05:33:57"
+      }
+    },
+    ...
+  ],
+  ```
+  Except for `"name"`, all properties are optional. You can supply a description, a color, a location (optionally with `position` and `rotation`) and a time.
+* It is now required to have a `"graphics": {}` object, even if it is empty.
+* The existence of anchors is now defined in a two-element array like this:
+  ```json
+  "Sun": {
+    "center": "Sun",
+    "frame": "IAU_Sun",
+    "existence": [
+      "1950-01-02 00:00:00.000",
+      "2049-12-31 00:00:00.000"
+    ]
+  },
+  ```
+* All properties of `"csp-measurement-tools": {}` are now optional and can be omitted.
+* `"csp-fly-to-locations": {}` now simply displays all `"bookmarks"` with a given location. Therefore the plugin has no configuration option anymore.
+* The satellite configuration of `"csp-satellites"` has no `"transformation"` property anymore. The same effect can now be achieved with the `"position"`, `"rotation"` and `"scale"` properties of the anchor this satellite is attached to.