[dpdk-dev,0/2] doc: refactored fig and table nums into references

  > -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Wednesday, April 29, 2015 5:13 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH 0/2] doc: refactored fig and table nums
> into references
> 
> is really a great work but I think it's not reasonnable to require
> sphinx 1.3. As almost nobody is using this version, it would be equivalent
> to prevent users and developers to generate the doc by themselves.

Hi Thomas,

Yes. That is probably right.


> 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:

$ git diff doc/guides/conf.py


That is just a workaround though, and maybe not worth it either.

P.S. Also note, Sphinx 1.3.1 has a nice but very different default Html style. 

John
  

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
  

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Wednesday, May 13, 2015 8:08 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH 0/2] doc: refactored fig and table nums
> into references
> 
> 
> 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:


Hi Thomas,

I'll take a look at it and see if I can get something working.

John.
--
  

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Wednesday, May 13, 2015 8:08 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH 0/2] doc: refactored fig and table nums
> into references
> 
> 
> Unfortunately it gives this error:
> 	_pickle.PicklingError: Can't pickle <class 'XNumRefNode'>: attribute
> lookup XNumRefNode on builtins failed
> 

Hi Thomas,

I ran into similar pickle.py issues trying to subclass the node.reference classes within sphinx.

I was able to workaround it without a subclass. I'll submit a rebased V2 of the Figure/Table numbering patchset with updates to conf.py. You can review the workaround there.

John.
--