From: Thomas Monjalon <thomas.monjalon@6wind.com>
To: "Mcnamara, John" <john.mcnamara@intel.com>
Cc: dev@dpdk.org
Subject: Re: [dpdk-dev] [PATCH 0/2] doc: refactored fig and table nums into references
Date: Wed, 13 May 2015 21:07:30 +0200 [thread overview]
Message-ID: <2042378.YRHo6U96YW@xps13> (raw)
In-Reply-To: <B27915DBBA3421428155699D51E4CFE2F183E8@IRSMSX103.ger.corp.intel.com>
2015-04-30 13:34, Mcnamara, John:
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> > It produces this error:
> > ERROR: Unknown interpreted text role "numref".
> >
> > Do you think it's possible to implement a fallback in our conf.py in order
> > to ignore this new role if not supported?
>
> It would be possible but a full implementation probably wouldn't be worth it.
> We could add a workaround like the following to conf.py that would just
> render the figure/table ref numbers as the target name as a fallback.
> That would allow people to generate the docs with older versions of sphinx:
>
> +from docutils import nodes
> +from distutils.version import LooseVersion
> +from sphinx import __version__ as sphinx_version
> +
> +# Workaround to ignore :numref: in older versions of Sphinx.
> +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.')
> + app.add_generic_role('numref', nodes.emphasis)
>
> That is just a workaround though, and maybe not worth it either.
The error is removed so it's better.
With this patch, a figure reference looks like this:
:numref:`figure_single_port_nic` Virtualization for a Single Port NIC in SR-IOV Mode
The rst line is:
:numref:`figure_single_port_nic` :ref:`figure_single_port_nic`
I was trying to replace the numref output by a working link with "figure" as label.
This is my trial to mimic :ref: as a first step:
8<------------------------
from docutils import nodes
from distutils.version import LooseVersion
from sphinx import __version__ as sphinx_version
from sphinx import addnodes
from sphinx.roles import XRefRole
class XNumRefNode(addnodes.pending_xref):
def __init__(self, rawsource='', *children, **attributes):
attributes['reftype'] = 'ref'
super(XNumRefNode, self).__init__(rawsource, *children, **attributes)
class XNumRefRole(XRefRole):
def __init__(self):
super(XNumRefRole, self).__init__(nodeclass=XNumRefNode, innernodeclass=nodes.emphasis, warn_dangling=True)
def setup(app):
if LooseVersion(sphinx_version) < LooseVersion('1.3.1'):
print('Upgrade sphinx to version >= 1.3.1 for '
'improved Figure/Table number handling.')
app.add_node(XNumRefNode)
app.add_role('numref', XNumRefRole())
8<------------------------
Unfortunately it gives this error:
_pickle.PicklingError: Can't pickle <class 'XNumRefNode'>: attribute lookup XNumRefNode on builtins failed
Help of python experts is welcome.
References:
http://sphinx-doc.org/markup/inline.html#role-numref
https://bitbucket.org/arjones6/sphinx-numfig/src/b2345f7d9fabefbd103c31cc0c4c26c68b29ac6a/numfig.py
http://code.nabla.net/doc/sphinx/api/sphinx/addnodes/sphinx.addnodes.pending_xref.html
next prev parent reply other threads:[~2015-05-13 19:08 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-04-24 13:11 John McNamara
2015-04-24 13:11 ` [dpdk-dev] [PATCH 1/2] doc: refactored figure numbers " John McNamara
2015-04-24 13:11 ` [dpdk-dev] [PATCH 2/2] doc: refactored table " John McNamara
2015-04-29 16:12 ` [dpdk-dev] [PATCH 0/2] doc: refactored fig and table nums " Thomas Monjalon
2015-04-30 13:34 ` Mcnamara, John
2015-05-13 19:07 ` Thomas Monjalon [this message]
2015-05-14 10:41 ` Mcnamara, John
2015-05-18 10:48 ` Mcnamara, John
2015-05-18 11:15 ` [dpdk-dev] [PATCH v2 0/3] " John McNamara
2015-05-18 11:15 ` [dpdk-dev] [PATCH 1/3] doc: refactored figure numbers " John McNamara
2015-05-18 11:15 ` [dpdk-dev] [PATCH v2 3/3] doc: add sphinx numref compatibility workaround John McNamara
2015-05-18 11:34 ` [dpdk-dev] [PATCH v3 0/3] doc: refactored fig and table nums into references John McNamara
2015-05-18 11:34 ` [dpdk-dev] [PATCH v3 1/3] doc: refactored figure numbers " John McNamara
2015-05-18 11:34 ` [dpdk-dev] [PATCH v3 2/3] doc: refactored table " John McNamara
2015-05-18 11:34 ` [dpdk-dev] [PATCH v3 3/3] doc: add sphinx numref compatibility workaround John McNamara
2015-05-25 14:05 ` [dpdk-dev] [PATCH v3 0/3] doc: refactored fig and table nums into references Thomas Monjalon
2015-05-25 16:37 ` Mcnamara, John
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=2042378.YRHo6U96YW@xps13 \
--to=thomas.monjalon@6wind.com \
--cc=dev@dpdk.org \
--cc=john.mcnamara@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).