0

I am working on implementing a Python package that inherits from networkx. Networkx seems to use numpydoc, but also wraps certain parts of their docstrings in single backtick characters: `. This normally in rst files denotes italics, but in numpydoc this attempts to create a reference.

So when I have a file like the following where I use autodoc's autosummary directive:

.. currentmodule:: pywhy_graphs.classes.timeseries

.. autosummary:: 
   :toctree: generated/
   
   TimeSeriesGraph
   TimeSeriesDiGraph
   TimeSeriesMixedEdgeGraph

I get the following errors (I copy-pasted only 3 examples for the sake of space):

/Users/adam2392/Documents/pywhy-graphs/pywhy_graphs/classes/timeseries/timeseries.py:docstring of networkx.classes.graph.Graph.to_undirected:33: WARNING: py:obj reference target not found: G = nx.DiGraph(D)
/Users/adam2392/Documents/pywhy-graphs/pywhy_graphs/classes/timeseries/timeseries.py:docstring of networkx.classes.graph.Graph.update:25: WARNING: py:obj reference target not found: edges is None
/Users/adam2392/Documents/pywhy-graphs/pywhy_graphs/classes/timeseries/timeseries.py:docstring of networkx.classes.graph.Graph.update:25: WARNING: py:obj reference target not found: nodes is None

These come for example from docstrings like: https://github.com/networkx/networkx/blob/83948b6dc61f507adb4cd1a71561eac9ed3b72ec/networkx/classes/graph.py#L1183.

Questions

  1. If I am using numpydoc, why am I getting this error, but networkx does not when building docs with sphinx?
  2. How do I disable, or workaround this error?
  3. I don't understand what is going on. If someone can help elaborate what I should do and why, that would be very helpful in learning Sphinx/numpydoc.
mzjn
  • 48,958
  • 13
  • 128
  • 248
ajl123
  • 1,172
  • 5
  • 17
  • 40
  • I have no idea, but if I were inheriting the documentation from another package, I would following their installation instructions https://github.com/networkx/networkx/blob/main/doc/README.md – Steve Piercy Jan 06 '23 at 08:09
  • NetworkX docs sets `obj` as the default role: https://github.com/networkx/networkx/blob/main/doc/conf.py#L238 – mzjn Jan 07 '23 at 13:29
  • I installed the package following their instructions. I tried setting `nitpicky=False` and there was no change. I'm also not sure why `NetworkX docs sets obj as the default role:` matters? – ajl123 Jan 07 '23 at 17:07
  • The issue is that `networkx` somehow doesn't treat these backticks as references, whereas normal numpydoc does. – ajl123 Jan 07 '23 at 17:26
  • Setting `obj` as the default role turns all strings enclosed in backticks into cross-references. `\`abc\`` is interpreted as `:obj:\`abc\``. – mzjn Jan 07 '23 at 18:47
  • And `obj` is the default role in numpydoc as well: https://github.com/numpy/numpydoc/blob/main/numpydoc/xref.py#L100 – mzjn Jan 07 '23 at 20:46
  • But `networkx` does not contain any errors when I build their documentation w/ numpydoc, so I'm confused how that is possible. – ajl123 Jan 08 '23 at 16:22
  • It is easy to generate the warning messages you are getting (with `nitpicky = True`). Setting `nitpicky = False` does not work for you apparently. I am stumped. – mzjn Jan 09 '23 at 08:44
  • I've been using Sphinx for 10+ years and I still don't know how to fix this issue properly. – astrojuanlu May 26 '23 at 15:31

0 Answers0