docs/engine: move existing docs into this subdirectory

I think we're going to want to maintain a separate docs tree for the
research app user guide, so let's get to work on setting that up.

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "docs/themes/wwtguide"]
-	path = docs/themes/wwtguide
+[submodule "docs/engine/themes/wwtguide"]
+	path = docs/engine/themes/wwtguide
 	url = https://github.com/WorldWideTelescope/zola-wwtguide.git

README.md

@@ -7,6 +7,8 @@
 [![npm](https://img.shields.io/npm/v/@wwtelescope/engine-helpers?label=@wwtelescope/engine-helpers)](https://www.npmjs.com/package/@wwtelescope/engine-helpers)
 [![npm](https://img.shields.io/npm/v/@wwtelescope/engine-types?label=@wwtelescope/engine-types)](https://www.npmjs.com/package/@wwtelescope/engine-types)
 [![npm](https://img.shields.io/npm/v/@wwtelescope/engine-vuex?label=@wwtelescope/engine-vuex)](https://www.npmjs.com/package/@wwtelescope/engine-vuex)
+[![npm](https://img.shields.io/npm/v/@wwtelescope/research-app?label=@wwtelescope/research-app)](https://www.npmjs.com/package/@wwtelescope/research-app)
+[![npm](https://img.shields.io/npm/v/@wwtelescope/research-app-messages?label=@wwtelescope/research-app-messages)](https://www.npmjs.com/package/@wwtelescope/research-app-messages)
 
 # The AAS WorldWide Telescope WebGL engine
 
@@ -34,7 +36,12 @@ Learn more about WWT [here][wwt-home].
    1. The core engine package in the `engine/` package.
    1. The engine tidied up into a [Vue]/[Vuex] module in `engine-vuex/`
    1. The WWT embed app intended for iframe inclusion in `embed/`
+   1. The WWT research app in `research-app/`
    1. The user-facing app for creating embed iframe code in `embed-creator/`
+1. Commands to serve the web apps:
+   1. `npm run serve-embed` to serve the embed app
+   1. `npm run serve-research` to serve the research app
+   1. `npm run serve-creator` to serve the embed creator app
 1. `npm run test` (mainly uses [mocha] and [chai])
 1. `npm run doc` (uses [TypeDoc])
 
@@ -62,6 +69,8 @@ The most important subdirectories are:
   engine into a reusable [Vue]/[Vuex] component
 - `@wwtelescope/embed` in `embed/`, a web application that turns WWT into a
   configurable, embeddable iframe
+- `@wwtelescope/research-app` in `research-app/`, an embeddable web application for
+  astrophysics research using WWT.
 - The narrative documentation in `docs/`
 
 README files inside the individual subdirectories give more information about
@@ -106,7 +115,7 @@ sequence is:
 [Lerna]: https://lerna.js.org/
 
 1. Run `git submodule update --init` to pull in needed Git submodules, namely
-   the documentation theme in `docs/themes/wwtguide`.
+   the documentation theme in `docs/*/themes/wwtguide`.
 1. Run `npx lerna bootstrap` to install all of the project dependencies and set
    up the necessary cross-links between individual packages in this repository.
 
@@ -131,7 +140,7 @@ of packages.)
 
 ## Building the full documentation
 
-Documentation is maintained in the `docs/` subdirectory. The documentation is a
+Documentation is maintained in subdirectories of `docs/`. The documentation is a
 Frankenstein combination of the autogenerated API documentation and narrative
 material written in [CommonMark Markdown]. The final HTML is assembled with the
 static site generator [Zola],
@@ -143,9 +152,9 @@ static site generator [Zola],
 1. Zola is fast and self-contained and [ridiculously easy to
    install][install-zola].
 1. The `npm run doc` command will install the autogenerated documentation into
-   `docs/static/`
-1. Running `zola build` in the `docs` subdirectory will assembled the final HTML
-   into `docs/public/`.
+   `docs/engine/static/`
+1. Running `zola build` in a subdirectory of `docs` will assembled the final HTML
+   into `docs/{subdir}/public/`.
 1. The command `zola check` will check the narrative docs for broken links.
 1. The command `zola serve` will serve the documentation using a local server
    with autoreload.

astro/tsconfig.json

@@ -24,8 +24,8 @@
     "src/**/*.ts"
   ],
   "typedocOptions": {
-    "readme": "../docs/astro-index.md",
-    "out": "../docs/static/apiref/astro",
+    "readme": "../docs/engine/astro-index.md",
+    "out": "../docs/engine/static/apiref/astro",
     "gaID": "UA-107473046-3",
     "excludePrivate": true,
     "listInvalidSymbolLinks": true

ci/azure-deployment.yml

@@ -225,12 +225,12 @@ jobs:
           -EndpointName wwtweb-prod `
           -PurgeContent '/research/$(RESEARCH_APP_DEPLOYMENT_TAG)/*'
 
-# Since the docs combine outputs from nearly every submodule, we deploy new
+# Since the engine docs combine outputs from nearly every submodule, we deploy new
 # versions on every update. Because the docs combine many different submodules,
 # that raises the question of what version number to assign. As a heuristic, we
 # track @wwtelescope/engine.
 
-- job: deploy_docs
+- job: deploy_engine_docs
   pool:
     vmImage: windows-latest
   variables:
@@ -246,25 +246,25 @@ jobs:
         # Docs release tag is `major.minor`.
         tag="$(cranko show version @wwtelescope/engine |cut -d. -f1,2)"
       fi
-      echo "docs deployment tag: $isMainDev, $isRelease => $tag"
-      echo "##vso[task.setvariable variable=DOCS_DEPLOYMENT_TAG;]$tag"
+      echo "engine docs deployment tag: $isMainDev, $isRelease => $tag"
+      echo "##vso[task.setvariable variable=ENGINE_DOCS_DEPLOYMENT_TAG;]$tag"
     displayName: Determine deployment tag
     env:
       isMainDev: ${{ parameters.isMainDev }}
       isRelease: ${{ parameters.isRelease }}
 
   - task: AzureFileCopy@3
-    displayName: Deploy documentation
+    displayName: Deploy engine documentation
     inputs:
-      SourcePath: '$(Pipeline.Workspace)/docs'
+      SourcePath: '$(Pipeline.Workspace)/docs-engine'
       azureSubscription: 'aas@wwtadmindotnetfoundation'
       Destination: 'AzureBlob'
       storage: 'wwtwebstatic'
       ContainerName: '$web'
-      blobPrefix: '_docs/webgl-reference/$(DOCS_DEPLOYMENT_TAG)'
+      blobPrefix: '_docs/webgl-reference/$(ENGINE_DOCS_DEPLOYMENT_TAG)'
 
   - task: AzurePowerShell@4
-    displayName: CDN purge - docs
+    displayName: CDN purge - engine docs
     inputs:
       azureSubscription: 'aas@wwtadmindotnetfoundation'
       azurePowerShellVersion: 'LatestVersion'
@@ -274,7 +274,7 @@ jobs:
           -ProfileName wwt-cdn-01 `
           -ResourceGroupName wwt-web01 `
           -EndpointName wwtwebdocs-prod `
-          -PurgeContent '/webgl-reference/$(DOCS_DEPLOYMENT_TAG)/*'
+          -PurgeContent '/webgl-reference/$(ENGINE_DOCS_DEPLOYMENT_TAG)/*'
 
 # Deployment jobs that should only happen on updates to `rc`, i.e.
 # primary releases.

ci/azure-main-build.yml

@@ -174,18 +174,18 @@ jobs:
 
   - bash: |
       set -xeuo pipefail
-      cd docs
-      ../zola check
-    displayName: Check Zola docs site
+      cd docs/engine
+      ../../zola check
+    displayName: Check Zola engine docs site
 
   - bash: |
       set -xeuo pipefail
-      cd docs
-      ../zola build -o $ARTIFACT_STAGING/docs
-    displayName: Zola docs build
+      cd docs/engine
+      ../../zola build -o $ARTIFACT_STAGING/docs-engine
+    displayName: Zola engine docs build
 
   - task: PublishPipelineArtifact@0
-    displayName: Publish docs artifacts
+    displayName: Publish engine docs artifacts
     inputs:
-      artifactName: docs
-      targetPath: $(Build.ArtifactStagingDirectory)/docs
+      artifactName: docs-engine
+      targetPath: $(Build.ArtifactStagingDirectory)/docs-engine

embed-common/tsconfig.json

@@ -24,8 +24,8 @@
     "src/**/*.ts"
   ],
   "typedocOptions": {
-    "readme": "../docs/embed-common-index.md",
-    "out": "../docs/static/apiref/embed-common",
+    "readme": "../docs/engine/embed-common-index.md",
+    "out": "../docs/engine/static/apiref/embed-common",
     "gaID": "UA-107473046-3",
     "excludePrivate": true,
     "listInvalidSymbolLinks": true

embed/package.json

@@ -40,7 +40,7 @@
   "repository": "github:WorldWideTelesope/wwt-webgl-engine",
   "scripts": {
     "build": "vue-cli-service build",
-    "doc": "copyfiles -u 1 \"dist/**/*\" ../docs/static/embed",
+    "doc": "copyfiles -u 1 \"dist/**/*\" ../docs/engine/static/embed",
     "lint": "vue-cli-service lint src",
     "serve": "vue-cli-service serve"
   },

engine-helpers/tsconfig.json

@@ -24,8 +24,8 @@
     "src/**/*.ts"
   ],
   "typedocOptions": {
-    "readme": "../docs/engine-helpers-index.md",
-    "out": "../docs/static/apiref/engine-helpers",
+    "readme": "../docs/engine/engine-helpers-index.md",
+    "out": "../docs/engine/static/apiref/engine-helpers",
     "gaID": "UA-107473046-3",
     "excludePrivate": true,
     "listInvalidSymbolLinks": true

engine-types/tsconfig.json

@@ -24,8 +24,8 @@
     "src/**/*.ts"
   ],
   "typedocOptions": {
-    "readme": "../docs/engine-types-index.md",
-    "out": "../docs/static/apiref/engine-types",
+    "readme": "../docs/engine/engine-types-index.md",
+    "out": "../docs/engine/static/apiref/engine-types",
     "gaID": "UA-107473046-3",
     "excludePrivate": true,
     "listInvalidSymbolLinks": true

engine-vuex/tsconfig.json

@@ -26,8 +26,8 @@
     "src/**/*.vue"
   ],
   "typedocOptions": {
-    "readme": "../docs/engine-vuex-index.md",
-    "out": "../docs/static/apiref/engine-vuex",
+    "readme": "../docs/engine/engine-vuex-index.md",
+    "out": "../docs/engine/static/apiref/engine-vuex",
     "gaID": "UA-107473046-3",
     "excludePrivate": true,
     "listInvalidSymbolLinks": true

engine/package.json

@@ -11,9 +11,6 @@
   "description": "The AAS WorldWide Telescope WebGL engine",
   "files": [
     ".eslintrc.json",
-    "docs/**/*.html",
-    "docs/**/*.md",
-    "docs/**/*.toml",
     "scriptsharp-0.8.0/ss.js",
     "src/*.js",
     "src/*.ts",

engine/tsconfig.json

@@ -32,8 +32,8 @@
     "node_modules"
   ],
   "typedocOptions": {
-    "readme": "../docs/engine-index.md",
-    "out": "../docs/static/apiref/engine",
+    "readme": "../docs/engine/engine-index.md",
+    "out": "../docs/engine/static/apiref/engine",
     "gaID": "UA-107473046-3",
     "listInvalidSymbolLinks": true,
     "excludeExternals": true,

research-app-messages/src/index.ts

@@ -1,7 +1,7 @@
 // Copyright 2020 the .NET Foundation
 // Licensed under the MIT License
 
-// Toplevel documentation found at @/docs/research-app-messages-index.md
+// Toplevel documentation found at @/docs/engine/research-app-messages-index.md
 
 import * as classicPywwt from './classic_pywwt';
 

research-app-messages/tsconfig.json

@@ -22,8 +22,8 @@
   },
   "include": ["src/*"],
   "typedocOptions": {
-    "readme": "../docs/research-app-messages-index.md",
-    "out": "../docs/static/apiref/research-app-messages",
+    "readme": "../docs/engine/research-app-messages-index.md",
+    "out": "../docs/engine/static/apiref/research-app-messages",
     "gaID": "UA-107473046-3",
     "excludePrivate": true,
     "listInvalidSymbolLinks": true