diff --git a/CMakeLists.txt b/CMakeLists.txt index f56d5fe73a..b062a18ec1 100644 --- a/CMakeLists.txt +++ b/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) diff --git a/admin/tools/docker/base/Dockerfile b/admin/tools/docker/base/Dockerfile index 114fccb405..8c1c1da895 100644 --- a/admin/tools/docker/base/Dockerfile +++ b/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] \ diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index ba65b13af5..0000000000 --- a/doc/.gitignore +++ /dev/null @@ -1 +0,0 @@ -/_build/ diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000000..0b88a81811 --- /dev/null +++ b/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 +) diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 3fff092987..0000000000 --- a/doc/Makefile +++ /dev/null @@ -1,32 +0,0 @@ -BUILDDIR = _build - -.PHONY: help -help: - @echo "Available commands:" - @echo " init to install Python dependencies" - @echo " clean delete the exisiting build" - @echo " html to make standalone HTML files" - @echo " linkcheck to check all external links for integrity" - @echo " help this command" - - -.PHONY: init -init: - pip install -U -r requirements.txt - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - -.PHONY: html -html: - sphinx-build -b html -d $(BUILDDIR)/doctrees -n -W . $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -.PHONY: linkcheck -linkcheck: - sphinx-build -b linkcheck -d $(BUILDDIR)/doctrees -n -W . $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." diff --git a/doc/cmake/FindSphinx.cmake b/doc/cmake/FindSphinx.cmake new file mode 100644 index 0000000000..fee0e3eef6 --- /dev/null +++ b/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) diff --git a/doc/conf.py b/doc/conf.py index c616665d10..a2cb3c58be 100644 --- a/doc/conf.py +++ b/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.+)", 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 # " v 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. diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index 5507325a58..0000000000 --- a/doc/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -documenteer -lsst-sphinx-bootstrap-theme>=0.2.0,<0.3.0