From 137f574d13fed8c1814541254bbd721f9822726a Mon Sep 17 00:00:00 2001
From: "W. Trevor King" <wking@tremily.us>
Date: Sat, 1 Nov 2014 09:44:08 -0700
Subject: [PATCH] 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
---
 eclass/sphinx.eclass | 77 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 eclass/sphinx.eclass

diff --git a/eclass/sphinx.eclass b/eclass/sphinx.eclass
new file mode 100644
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
-- 
2.26.2