Make docs buildable in build container

CMakeLists.txt

@@ -1,7 +1,6 @@
 cmake_minimum_required(VERSION 3.12)
 
 project(Qserv
-    VERSION 0.8
     DESCRIPTION "The Qserv distributed parallel database"
     LANGUAGES CXX
 )
@@ -11,8 +10,8 @@ enable_testing()
 include(GNUInstallDirs)
 set(CMAKE_INSTALL_PREFIX ${PROJECT_BINARY_DIR}/install)
 
+add_subdirectory(doc)
 add_subdirectory(extern/log)
 add_subdirectory(extern/partition)
 add_subdirectory(extern/sphgeom)
-
 add_subdirectory(src)

admin/tools/docker/base/Dockerfile

@@ -127,8 +127,11 @@ RUN pip3 install \
     click \
     deprecated \
     docker-compose \
+    documenteer \
     jinja2 \
+    ltd-conveyor \
     mypy \
+    sphinx-rtd-theme \
     mysql-connector-python \
     numpy \
     pybind11[global] \

doc/CMakeLists.txt

@@ -0,0 +1,29 @@
+set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+
+find_package(Sphinx REQUIRED)
+
+add_custom_target(docs-html
+    COMMENT "Building HTML documentation with Sphinx"
+    COMMAND ${SPHINX_EXECUTABLE}
+        -b html
+        -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees
+        -n -W
+        ${CMAKE_CURRENT_SOURCE_DIR}
+        ${CMAKE_CURRENT_BINARY_DIR}/html
+    BYPRODUCTS
+        ${CMAKE_CURRENT_BINARY_DIR}/doctrees
+        ${CMAKE_CURRENT_BINARY_DIR}/html
+)
+
+add_custom_target(docs-linkcheck
+    COMMENT "Checking documentation links with Sphinx"
+    COMMAND ${SPHINX_EXECUTABLE}
+        -b linkcheck
+        -d ${CMAKE_CURRENT_BINARY_DIR}/doctrees
+        -n -W
+        ${CMAKE_CURRENT_SOURCE_DIR}
+        ${CMAKE_CURRENT_BINARY_DIR}/linkcheck
+    BYPRODUCTS
+        ${CMAKE_CURRENT_BINARY_DIR}/doctrees
+        ${CMAKE_CURRENT_BINARY_DIR}/linkcheck
+)

doc/cmake/FindSphinx.cmake

@@ -0,0 +1,11 @@
+find_program(SPHINX_EXECUTABLE NAMES sphinx-build
+    DOC "Sphinx documentation generator"
+)
+
+include(FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args(Sphinx DEFAULT_MSG
+    SPHINX_EXECUTABLE
+)
+
+mark_as_advanced(SPHINX_EXECUTABLE)

doc/conf.py

@@ -1,9 +1,11 @@
 """Sphinx configurations for the qserv.lsst.io documentation build."""
 
+import contextlib
 import os
+import re
 import sys
 
-import lsst_sphinx_bootstrap_theme
+from documenteer.sphinxconfig.utils import form_ltd_edition_name
 
 # -- General configuration ----------------------------------------------------
 
@@ -19,37 +21,41 @@
 source_suffix = ".rst"
 
 root_doc = "index"
-master_doc = "index"  # deprecated in 4.0
 
+# General information about the project.
 project = "Qserv"
-
-# TODO
-copyright = ""
-
-author = "Rubin Observatory"
+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.
-# TODO either set these manually here, or extract from e.g. env variables.
-version = "X.Y.Z"
-release = "X.Y.Z"
+
+# 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
+
+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 = ["_build", "Makefile"]
+exclude_patterns = ["CMakeLists.txt"]
 
 # The reST default role cross-links Python (used for this markup: `text`)
 default_role = "py:obj"
 
-# -- ReStructuredText epilog for common links/substitutions ---------------
-
-rst_epilog = """
-
-.. _conda-forge: https://conda-forge.org
-.. _conda: https://conda.io/en/latest/index.html
-"""
-
 # -- Options for linkcheck builder --------------------------------------------
 
 linkcheck_retries = 2
@@ -65,34 +71,39 @@
 
 # -- Options for html builder -------------------------------------------------
 
-templates_path = [
-    lsst_sphinx_bootstrap_theme.get_html_templates_path(),
-]
-html_theme = "lsst_sphinx_bootstrap_theme"
-html_theme_path = [lsst_sphinx_bootstrap_theme.get_html_theme_path()]
+html_theme = "sphinx_rtd_theme"
 
 # Variables available for Jinja templates
-html_context = {}
+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 = {"logotext": project}
+html_theme_options = {
+    "collapse_navigation": False,
+    "navigation_depth": -1
+}
 
 # 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"
+# 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"]
+# html_static_path = ["_static"]
 
 # If true, links to the reST sources are added to the pages.
-html_show_sourcelink = False
+# html_show_sourcelink = False
 
 # -- Intersphinx --------------------------------------------------------------
 # For linking to other Sphinx documentation.