From 8b2e98e61162ac0346a79dc422a7c5f2701e5f1b Mon Sep 17 00:00:00 2001
From: Fritz Mueller <fritzm@slac.stanford.edu>
Date: Wed, 12 Jul 2023 17:47:04 +0000
Subject: [PATCH] Update build image to documenteer[guide]

---
 admin/tools/docker/base/Dockerfile |  2 +-
 doc/conf.py                        | 79 +-----------------------------
 doc/documenteer.toml               |  5 ++
 doc/templates/overview.html        |  2 +
 4 files changed, 10 insertions(+), 78 deletions(-)
 create mode 100644 doc/documenteer.toml

diff --git a/admin/tools/docker/base/Dockerfile b/admin/tools/docker/base/Dockerfile
index b385968e92..54ec8b99c9 100644
--- a/admin/tools/docker/base/Dockerfile
+++ b/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 \
diff --git a/doc/conf.py b/doc/conf.py
index 22efc73f8d..fe6b857355 100644
--- a/doc/conf.py
+++ b/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),
-}
diff --git a/doc/documenteer.toml b/doc/documenteer.toml
new file mode 100644
index 0000000000..7ae39c6f41
--- /dev/null
+++ b/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"
diff --git a/doc/templates/overview.html b/doc/templates/overview.html
index 6cd432799c..808666e237 100644
--- a/doc/templates/overview.html
+++ b/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>