sphinx.eclass: Make local intersphinx links easier to setup

See:
https://bugs.gentoo.org/show_bug.cgi?id=522794
  dev-python/python-docs: Install files in a more predictable location
https://bugs.gentoo.org/show_bug.cgi?id=526186
  distutils-r1 / python-utils-r1: need better way of installing Sphinx docs
https://bugs.gentoo.org/show_bug.cgi?id=521768
  dev-python/python-docs-3.4.0 doesn't install objects.inv for intersphinx
https://bugs.gentoo.org/show_bug.cgi?id=517478
  dev-python/flask-cors - A Flask extension adding a decorator for CORS support

diff --git a/eclass/sphinx.eclass b/eclass/sphinx.eclass
new file mode 100644 (file)
index 0000000..349d7f3
--- /dev/null
+++ b/eclass/sphinx.eclass
@@ -0,0 +1,77 @@
+# Copyright 1999-2014 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header:$
+
+# @ECLASS: sphinx
+# @MAINTAINER:
+# W. Trevor King <wking@tremily.us>
+# @AUTHOR:
+# W. Trevor King <wking@tremil.us>
+# @BLURB: Utilities for building Sphinx documentation.
+# @DESCRIPTION:
+# Currently provided functions:
+# * sphinx_local_objects, which adjusts intersphinx links to point to
+#   local documentation.
+
+if [[ -z ${_SPHINX_ECLASS} ]]; then
+_SPHINX_ECLASS=1
+
+case "${EAPI:-0}" in
+       0|1|2|3)
+               die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
+               ;;
+       4|5)
+               ;;
+       *)
+               die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
+               ;;
+esac
+
+# @ECLASS-VARIABLE: SPHINX_CONF_PY
+# @DEFAULT_UNSET
+# @DESCRIPTION:
+# The path to the Sphinx conf.py (usually doc/conf.py or some such).
+#
+# You don't need to set this if you're not using sphinx_local_objects.
+
+# @FUNCTION: sphinx_local_objects
+# @USAGE: <linked-package-dependency> <sed-regex-matching-the-upstream-entry>
+# @DESCRIPTION:
+# Replace an upstream intersphinx entry in SPHINX_CONF_PY with a
+# pointer to local documentation.  For example:
+#
+#   sphinx_local_objects dev-python/python-docs:2.7 "'http://docs.python.org/': None"
+#
+# This command dies on failure.
+sphinx_local_objects() {
+       debug-print-function ${FUNCNAME} "${@}"
+       local LINKED_PACKAGE_DEPENDENCY="${1}"
+       local SED_REGEX="${2}"
+       if [ -z "${SPHINX_CONF_PY}" ]
+       then
+               die "empty SPHINX_CONF_PY"
+       fi
+       if [ ! -f "${SPHINX_CONF_PY}" ]
+       then
+               die "missing SPHINX_CONF_PY (${SPHINX_CONF_PY})"
+       fi
+
+       local DEPENDENCY_ATOM=$(best_version --host-root "${LINKED_PACKAGE_DEPENDENCY}")
+       local DEPENDENCY_NAME_VERSION="${DEPENDENCY_ATOM#*/}"
+       local DEPENDENCY_DOC="/usr/share/doc/"${DEPENDENCY_NAME_VERSION}/html"
+       local DEPENDENCY_INVENTORY="${DEPENDENCY_DOC}/objects.inv"
+
+       if [ ! -f "${DEPENDENCY_INVENTORY}" ]
+       then
+               die "missing objects.inv for ${LINKED_PACKAGE_DEPENDENCY} (${DEPENDENCY_INVENTORY})"
+       fi
+
+       sed -i "s|'http://docs.python.org/': None|'${PYTHON_DOC}': '${PYTHON_DOC_INVENTORY}'|" docs/conf.py || die
+
+       set -- sed -i -e "s@${SED_REGEX}@'${DEPENDENCY_DOC}': '${DEPENDENCY_INVENTORY}'@" "${SPHINX_CONF_PY}"
+
+       echo "${@}" >&2
+       "${@}" || die
+}
+
+fi