DM-41687: Adopt documenteer "guide" style for Qserv documentation

.github/workflows/ci.yml

@@ -214,20 +214,14 @@ jobs:
           QSERV_GH_HEAD_REF: ${{ github.head_ref }}
           QSERV_GH_REF: ${{ github.ref }}
 
-      # 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
+        if: needs.update-base-images.outputs.build-rebuilt == 'True' || steps.filter.outputs.docs == 'true'
         uses: lsst-sqre/ltd-upload@v1
         with:
-          project: "qserv"
+          project: "Qserv"
           dir: "build/doc/html"
           username: ${{ secrets.LTD_USERNAME }}
           password: ${{ secrets.LTD_PASSWORD }}
-        if: >
-          (github.event_name != 'pull_request' || startsWith(github.head_ref, 'tickets/'))
-          && (needs.update-base-images.outputs.build-rebuilt == 'True' || steps.filter.outputs.docs == 'true')
 
   update-run-image:
     name: Update Qserv image

admin/tools/docker/base/Dockerfile

@@ -140,7 +140,7 @@ RUN pip3 install \
     "click==8.1.3" \
     deprecated \
     docker-compose \
-    documenteer \
+    documenteer[guide] \
     jinja2 \
     "sphinx-rtd-theme>=1.2.0rc3" \
     mypy \

doc/conf.py

@@ -1,35 +1,14 @@
-"""Sphinx configurations for the qserv.lsst.io documentation build."""
+from documenteer.conf.guide import *
 
 import contextlib
 import os
 import re
-import sys
 
 from documenteer.sphinxconfig.utils import form_ltd_edition_name
 
-# -- General configuration ----------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.ifconfig",
-    "documenteer.sphinxext",
-]
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["templates"]
 
-source_suffix = ".rst"
-
-root_doc = "index"
-
-# General information about the project.
-project = "Qserv"
-copyright = "2016-2022 Association of Universities for Research in Astronomy, Inc. (AURA)"
-author = "LSST Data Management"
-
 # 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.
@@ -50,20 +29,9 @@
 # The full version, including alpha/beta/rc tags.
 release = version
 
-html_last_updated_fmt = ""
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-# exclude_patterns = []
-
-# The reST default role cross-links Python (used for this markup: `text`)
-default_role = "py:obj"
-
-# -- Options for linkcheck builder --------------------------------------------
-
-linkcheck_retries = 2
-
-linkcheck_timeout = 15
+exclude_patterns = ["misc", "CMakeLists.txt"]
 
 # Add any URL patterns to ignore (e.g. for private sites, or sites that
 # are frequently down).
@@ -72,49 +40,6 @@
     r"^https://dev.lsstcorp.org/trac"
 ]
 
-# -- Options for html builder -------------------------------------------------
-
-html_theme = "sphinx_rtd_theme"
-
-# Variables available for Jinja templates
-html_context = {
-    "display_github": True,
-    "github_user": "lsst",
-    "github_repo": "qserv",
-    "github_version": git_ref + '/',
-    "conf_py_path": "doc/"
-}
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-html_theme_options = {
-}
-
-# The name for this set of Sphinx documents.  If unset, it defaults to
-# "<project> v<release> documentation".
-# html_title = ""
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-# html_short_title = "Qserv"
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
-
-# If true, links to the reST sources are added to the pages.
-# html_show_sourcelink = False
-
 html_additional_pages = {
     "index": "overview.html"
 }
-
-# -- Intersphinx --------------------------------------------------------------
-# For linking to other Sphinx documentation.
-# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
-
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3/", None),
-    "pipelines": ("https://pipelines.lsst.io/", None),
-}

doc/documenteer.toml

@@ -0,0 +1,5 @@
+[project]
+title = "Qserv"
+copyright = "2015-2023 Association of Universities for Research in Astronomy, Inc. (AURA)"
+base_url = "https://qserv.lsst.io"
+github_url = "https://github.com/lsst/qserv"

doc/templates/overview.html

@@ -35,6 +35,7 @@ <h1>Qserv documentation</h1>
       </p>
     </td>
   </tr></table>
+  <br>
 
   <p><strong>Indices and tables:</strong></p>
 
@@ -56,6 +57,7 @@ <h1>Qserv documentation</h1>
       </p>
     </td>
   </tr></table>
+  <br>
 
   <p><strong>External links:</strong></p>