From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id 57553C324 for ; Mon, 18 May 2015 13:35:23 +0200 (CEST) Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by orsmga101.jf.intel.com with ESMTP; 18 May 2015 04:35:22 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.13,453,1427785200"; d="scan'208";a="495012662" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by FMSMGA003.fm.intel.com with ESMTP; 18 May 2015 04:35:20 -0700 Received: from sivswdev02.ir.intel.com (sivswdev02.ir.intel.com [10.237.217.46]) by irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id t4IBZJGF023278; Mon, 18 May 2015 12:35:19 +0100 Received: from sivswdev02.ir.intel.com (localhost [127.0.0.1]) by sivswdev02.ir.intel.com with ESMTP id t4IBZJ0d004236; Mon, 18 May 2015 12:35:19 +0100 Received: (from jmcnam2x@localhost) by sivswdev02.ir.intel.com with id t4IBZJsr004232; Mon, 18 May 2015 12:35:19 +0100 From: John McNamara To: dev@dpdk.org Date: Mon, 18 May 2015 12:34:08 +0100 Message-Id: <1431948848-3842-4-git-send-email-john.mcnamara@intel.com> X-Mailer: git-send-email 1.7.4.1 In-Reply-To: <1431948848-3842-1-git-send-email-john.mcnamara@intel.com> References: <1429881109-16684-1-git-send-email-john.mcnamara@intel.com> <1431948848-3842-1-git-send-email-john.mcnamara@intel.com> Subject: [dpdk-dev] [PATCH v3 3/3] doc: add sphinx numref compatibility workaround X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 18 May 2015 11:35:26 -0000 This change adds some simple handling for the :numref: directive for Sphinx versions prior to 1.3.1. This allows the Guides documentation to be built with older versions of Sphinx and still produce reasonable results. The patch replaces the :numref: reference with a link to the target (for all Sphinx doc types). It doesn't try to label figures/tables. Full numref support with automatic figure/table numbering and links can be obtained by upgrading to Sphinx 1.3.1 or later. Signed-off-by: John McNamara --- doc/guides/conf.py | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/doc/guides/conf.py b/doc/guides/conf.py index 1bc031f..cab97ac 100644 --- a/doc/guides/conf.py +++ b/doc/guides/conf.py @@ -31,6 +31,9 @@ import subprocess from sphinx.highlighting import PygmentsBridge from pygments.formatters.latex import LatexFormatter +from docutils import nodes +from distutils.version import LooseVersion +from sphinx import __version__ as sphinx_version project = 'DPDK' @@ -72,6 +75,7 @@ latex_elements = { 'preamble': latex_preamble } + # Override the default Latex formatter in order to modify the # code/verbatim blocks. class CustomLatexFormatter(LatexFormatter): @@ -82,3 +86,79 @@ class CustomLatexFormatter(LatexFormatter): # Replace the default latex formatter. PygmentsBridge.latex_formatter = CustomLatexFormatter + + +# The following hook functions add some simple handling for the :numref: +# directive for Sphinx versions prior to 1.3.1. The functions replace the +# :numref: reference with a link to the target (for all Sphinx doc types). It +# doesn't try to label figures/tables. + +def numref_role(reftype, rawtext, text, lineno, inliner): + """ + Add a Sphinx role to handle numref references. Note, we can't convert the + link here because the doctree isn't build and the target information isn't + available. + + """ + + # Add an identifier to distinguish numref from other references. + newnode = nodes.reference('', + '', + refuri='_local_numref_#%s' % text, + internal=True) + + return [newnode], [] + + +def process_numref(app, doctree, from_docname): + """ + Process the numref nodes once the doctree has been built and prior to + writing the files. The processing involves replacing the numref with a + link plus text to indicate if it is a Figure or Table link. + + """ + env = app.builder.env + + # Iterate over the reference nodes in the doctree. + for node in doctree.traverse(nodes.reference): + target = node.get('refuri', '') + + # Look for numref nodes. + if target.startswith('_local_numref_#'): + target = target.replace('_local_numref_#', '') + + # Get the target label and link information from the Sphinx env. + data = env.domains['std'].data + docname, label, _ = data['labels'].get(target, ('', '', '')) + relative_url = app.builder.get_relative_uri(from_docname, docname) + + # Add a text label to the link. + if target.startswith('figure'): + caption = 'Figure' + elif target.startswith('table'): + caption = 'Table' + else: + caption = 'Link' + + # Create a new reference node with the updated link information. + newnode = nodes.reference('', + caption, + refuri='%s#%s' % (relative_url, label), + internal=True) + + # Replace the node. + node.replace_self(newnode) + + +def setup(app): + + if LooseVersion(sphinx_version) < LooseVersion('1.3.1'): + + print('[dpdk docs] Upgrade sphinx to version >= 1.3.1 for ' + 'improved Figure/Table number handling.') + + # Add a role to handle :numref: references. + app.add_role('numref', numref_role) + + # Process the numref references once the doctree has been created. + app.connect('doctree-resolved', process_numref) -- 1.8.1.4