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

["Mcnamara, John" <john.mcnamara@intel.com>]

> -----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
diff --git a/doc/guides/conf.py b/doc/guides/conf.py
index 1bc031f..bbf40f1 100644
--- a/doc/guides/conf.py
+++ b/doc/guides/conf.py
@@ -82,3 +82,16 @@ class CustomLatexFormatter(LatexFormatter):
 
 # Replace the default latex formatter.
 PygmentsBridge.latex_formatter = CustomLatexFormatter
+
+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.

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

John