Merge pull request #887 from lsst/tickets/DM-48638

DM-48638: Update Qserv documentation config

.github/workflows/ci.yml

@@ -170,6 +170,7 @@ jobs:
     name: Documentation
     runs-on: ubuntu-20.04
     needs: [image-names, update-base-images]
+    if: false  # Disable old documentation workflow pending migration to new one
     steps:
 
       - name: Install python
@@ -332,7 +333,7 @@ jobs:
         run: |
             ./admin/local/cli/qserv --log-level DEBUG itest-http-ingest \
             --qserv-image ${{ needs.image-names.outputs.qserv-image }}
-  
+
       - name: Check Qserv containers
         if: always()
         run: docker ps -a

.github/workflows/docs.yaml

@@ -0,0 +1,54 @@
+name: Build and upload documentation
+
+"on":
+  merge_group: {}
+  pull_request: {}
+  push:
+    branches-ignore:
+      # These should always correspond to pull requests, so ignore them for
+      # the push trigger and let them be triggered by the pull_request
+      # trigger, avoiding running the workflow twice.  This is a minor
+      # optimization so there's no need to ensure this is comprehensive.
+      - "dependabot/**"
+      - "gh-readonly-queue/**"
+      - "renovate/**"
+      - "tickets/**"
+      - "u/**"
+  release:
+    types: [published]
+
+jobs:
+  docs:
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for setuptools_scm
+
+      - name: Run tox
+        uses: lsst-sqre/run-tox@v1
+        with:
+          python-version: "3.12"
+          tox-envs: "docs"
+          # Add docs-linkcheck when the docs and PyPI package are published
+          # tox-envs: "docs,docs-linkcheck"
+          tox-plugins: tox-uv
+
+      # Only attempt documentation uploads for tagged releases and pull
+      # requests from ticket branches in the same repository.  This avoids
+      # version clutter in the docs and failures when a PR doesn't have access
+      # to secrets.
+      - name: Upload to LSST the Docs
+        uses: lsst-sqre/ltd-upload@v1
+        with:
+          project: "Qserv"
+          dir: "doc/_build/html"
+          username: ${{ secrets.LTD_USERNAME }}
+          password: ${{ secrets.LTD_PASSWORD }}
+        if: >
+          github.event_name != 'merge_group'
+          && (github.event_name != 'pull_request'
+              || startsWith(github.head_ref, 'tickets/'))

.gitignore

@@ -15,3 +15,4 @@
 /nbproject/
 /.vscode/
 /qserv/
+/doc/_build

doc/conf.py

@@ -1,31 +1,5 @@
 from documenteer.conf.guide import *
 
-import contextlib
-import os
-import re
-
-from documenteer.sphinxconfig.utils import form_ltd_edition_name
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-
-# The short X.Y version.
-github_ref = os.getenv("GITHUB_REF")
-if github_ref is None:
-    with contextlib.closing(os.popen("git symbolic-ref HEAD")) as p:
-        github_ref = p.read().strip()
-match = re.match(r"refs/(heads|tags|pull)/(?P<ref>.+)", github_ref)
-if not match:
-    git_ref = "main"
-else:
-    git_ref = match.group("ref")
-
-version = form_ltd_edition_name(git_ref)
-
-# The full version, including alpha/beta/rc tags.
-release = version
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = ["misc", "CMakeLists.txt"]

doc/index.rst

@@ -1,4 +1,10 @@
+Qserv
+=====
+
+Qserv is an open source, massively parallel, distributed SQL database designed to host the petascale astronomical catalogs of the `Rubin Observatory <https://rubinobservatory.org/>`_.
+
 .. toctree::
+   :maxdepth: 1
 
    /intro/index
    /admin/index

tox.ini

@@ -0,0 +1,22 @@
+[tox]
+envlist = docs,docs-linkcheck
+isolated_build = False
+
+[testenv]
+skip_install = True
+description = Python environment.
+deps =
+    sphinx
+    documenteer[guide]
+
+[testenv:docs]
+description = Build documentation (HTML) with Sphinx.
+commands =
+    sphinx-build --keep-going -n -W -T -b html -d {envtmpdir}/doctrees doc doc/_build/html
+
+[testenv:docs-linkcheck]
+description = Check links in the documentation.
+allowlist_externals =
+    make
+commands =
+    make linkcheck