Set up docs build and deploy logic

Pretty standard approach here.

Also tidy up a bit about the GitHub Pages update functionality. Note
that we separate the Pages bit from the main docs so that the "latest"
docs can easily link to the latest stable frontend release.

.gitmodules

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

ci/azure-build.yml

@@ -20,6 +20,11 @@ parameters:
       TARGET: x86_64-apple-darwin
       TOOLCHAIN: stable
 
+- name: 'zolaVersion'
+  default: '0.13.0'
+  type: string
+
+
 jobs:
 - ${{ each build in parameters.frontend_builds }}:
   - job: ${{ format('frontend_{0}', build.name) }}
@@ -101,3 +106,36 @@ jobs:
     inputs:
       targetPath: '$(Build.ArtifactStagingDirectory)/git-gh-pages'
       artifactName: git-gh-pages
+
+- job: docs
+  pool:
+    vmImage: ubuntu-20.04
+  steps:
+  - template: azure-job-setup.yml
+
+  - bash: |
+      set -xeuo pipefail
+      fn="zola-v${{ parameters.zolaVersion }}-x86_64-unknown-linux-gnu.tar.gz"
+      u="https://github.com/getzola/zola/releases/download/v${{ parameters.zolaVersion }}/$fn"
+      wget "$u"
+      tar xzf "$fn"
+      rm -rf "$fn"
+    displayName: Install Zola
+
+  - bash: |
+      set -xeuo pipefail
+      cd docs
+      ../zola check
+    displayName: Check docs site
+
+  - bash: |
+      set -xeuo pipefail
+      cd docs
+      ../zola build -o $ARTIFACT_STAGING/docs
+    displayName: Build docs HTML
+
+  - task: PublishPipelineArtifact@0
+    displayName: Publish docs artifacts
+    inputs:
+      artifactName: docs
+      targetPath: $(Build.ArtifactStagingDirectory)/docs

ci/azure-deployment.yml

@@ -61,6 +61,52 @@ jobs:
       tags: |
         $(DOCKER_DEPLOYMENT_TAG)
 
+- job: deploy_docs
+  pool:
+    vmImage: windows-latest
+  variables:
+  - group: Deployment Credentials
+  steps:
+  - template: azure-job-setup.yml
+
+  - bash: |
+      set -euo pipefail
+      if [[ ${isMainDev} == True ]] ; then
+        tag=latest
+      else
+        # Track the backend since that's where most of the action is
+        tag="$(cranko show version wwt_aligner |cut -d. -f1)"
+      fi
+      echo "docs deployment tag: $isMainDev, $isRelease => $tag"
+      echo "##vso[task.setvariable variable=DOCS_DEPLOYMENT_TAG;]$tag"
+    displayName: Determine deployment tag
+    env:
+      isMainDev: ${{ parameters.isMainDev }}
+      isRelease: ${{ parameters.isRelease }}
+
+  - task: AzureFileCopy@3
+    displayName: Deploy documentation
+    inputs:
+      SourcePath: '$(Pipeline.Workspace)/docs'
+      azureSubscription: 'aas@wwtadmindotnetfoundation'
+      Destination: 'AzureBlob'
+      storage: 'wwtwebstatic'
+      ContainerName: '$web'
+      blobPrefix: '_docs/aligner/$(DOCS_DEPLOYMENT_TAG)'
+
+  - task: AzurePowerShell@4
+    displayName: CDN purge - docs
+    inputs:
+      azureSubscription: 'aas@wwtadmindotnetfoundation'
+      azurePowerShellVersion: 'LatestVersion'
+      scriptType: 'inlineScript'
+      inline: |
+        Unpublish-AzCdnEndpointContent `
+          -ProfileName wwt-cdn-01 `
+          -ResourceGroupName wwt-web01 `
+          -EndpointName wwtwebdocs-prod `
+          -PurgeContent '/aligner/$(DOCS_DEPLOYMENT_TAG)/*'
+
 # Jobs that only run for releases
 
 - ${{ if parameters.isRelease }}:
@@ -107,7 +153,7 @@ jobs:
     pool:
       vmImage: ubuntu-20.04
     variables:
-      - group: Deployment Credentials
+    - group: Deployment Credentials
     steps:
     - template: azure-job-setup.yml
       parameters:
@@ -116,7 +162,10 @@ jobs:
         set -xeou pipefail
         git fetch $(Pipeline.Workspace)/git-gh-pages/gh-pages.bundle gh-pages
         git branch -f gh-pages FETCH_HEAD
-        git push --force origin gh-pages:gh-pages
-      displayName: Update GitHub pages website
+
+        if cranko show if-released --exit-code wwt-aligner-frontend; then
+          git push --force origin gh-pages:gh-pages
+        fi
+      displayName: Maybe update GitHub pages website
       env:
         GITHUB_TOKEN: $(GITHUB_TOKEN)

docs/.gitignore

@@ -0,0 +1 @@
+/public/

docs/config.toml

@@ -0,0 +1,8 @@
+base_url = "//docs.worldwidetelescope.org/aligner/1/"
+title = "WWT Aligner Manual"
+description = "The AAS WorldWide Telescope Aligner manual."
+theme = "wwtguide"
+
+[extra]
+github_base = "//github.com/WorldWideTelescope/wwt-aligner"
+google_analytics_id = "UA-107473046-3"

docs/content/_index.md

@@ -0,0 +1,23 @@
++++
+title = "WWT Aligner Manual"
+sort_by = "weight"
+insert_anchor_links = "right"
++++
+
+Welcome to the manual for the **WWT Aligner**, a tool that helps transfer
+astrometric information from scientific data (e.g., [FITS files]) to press
+release imagery (e.g., [JPEG files]).
+
+[FITS files]: https://fits.gsfc.nasa.gov/fits_documentation.html
+[JPEG files]: https://en.wikipedia.org/wiki/JPEG
+
+
+# Credits
+
+The WWT Aligner is part of the [AAS](https://aas.org/) [WorldWide Telescope]
+software system, although you do not need to use WWT in order for the Aligner to
+be useful for you. The development of the WWT Aligner was sponsored by the [Space
+Telescope Science Institute][stsci].
+
+[WorldWide Telescope]: http://www.worldwidetelescope.org/
+[stsci]: https://stsci.edu/

docs/content/commands/_index.md

@@ -0,0 +1,9 @@
++++
+title = "Command Reference"
+sort_by = "weight"
+insert_anchor_links = "right"
+weight = 500
++++
+
+This section provides reference documentation for the different sub-commands
+provided by the `wwt-aligner` command-line program.

docs/content/commands/update/index.md

@@ -0,0 +1,27 @@
++++
+title = "wwt-aligner update"
+weight = 2100
++++
+
+This command installs or updates the aligner tool implementation to the latest
+released code.
+
+# Synopsis
+
+```
+wwt-aligner update [--latest]
+```
+
+# Arguments
+
+By default, this command will update the Aligner’s [Docker image] to the latest
+stable software release. If the `--latest` option is provided, you’ll instead
+get the most recent “bleeding edge” version provided by WWT. This can be useful
+for beta-testing new features.
+
+[Docker image]: https://docs.docker.com/engine/reference/commandline/images/
+
+# Remarks
+
+To “undo” an update to the “latest” version, just rerun this command without the
+`--latest` argument. That will get you using the “stable” version again.

docs/content/installation/_index.md

@@ -0,0 +1,61 @@
++++
+title = "Installation"
+sort_by = "weight"
+insert_anchor_links = "right"
+weight = 100
++++
+
+Installing the WWT Aligner is a two-step process.
+
+
+# Prerequisites
+
+The WWT Aligner bundles up the complex [Astrometry.Net] software system using
+the [Docker] “containerization” system. In order to use the WWT Aligner, you
+must first [install Docker].
+
+[Astrometry.Net]: https://astrometry.net/
+[Docker]: https://www.docker.com/
+[install Docker]: https://docs.docker.com/get-docker/
+
+
+# Install the Frontend
+
+Once you’ve got Docker, you should install the “frontend” component, which is a
+small program that talks to your Docker installation.
+
+You can download the latest release of the frontend from GitHub [by following
+this link][latest]. Each release is published with versions of the frontend
+compiled for different operating systems.
+
+[latest]: https://worldwidetelescope.github.io/wwt-aligner/latest-release/
+
+To install the frontend, download the appropriate archive for your OS and unpack
+it. For instance, on a Mac you’ll want to download the file with the name
+looking like `wwt-aligner-frontend-<VERSION>-x86_64-apple-darwin.tar.gz`. This
+tarball will unpack to a single file, `wwt-aligner`.
+
+Put this file in a place where it can be found by your computer’s command-line
+prompt. On many systems, a reasonable default is the `/usr/local/bin` directory.
+You can set this up on the command line with:
+
+```sh
+$ sudo mv wwt-aligner /usr/local/bin/
+```
+
+You will know that this stage of the installation is successful when you can run
+the command `wwt-aligner` from your command line prompt and get some program
+usage help printed.
+
+
+# Download the Backend
+
+The final step is to download the bundled software in the form of a Docker
+“image”. The frontend can do this for you. Run:
+
+```sh
+$ wwt-aligner update
+```
+
+The image is about 500 megabytes in size, so it may take a little while to
+download. But once that’s done, you are ready to align some images!

docs/themes/wwtguide

@@ -0,0 +1 @@
+Subproject commit 13c43a8f5e536cbe6a1e5361d84bf7be73fcbfa4