How can I use intersphinx with Tensorflow and numpydoc?

Question

The main question here is where (if) there is an objects.inv for TensorFlow, but an example how to actually use it would be nice.

For example, I currently have the following docstring:

"""
Load the weights of a model stored in saver.

Parameters
----------
checkpoint_dir : str
    The directory of checkpoints.
sess : tf.Session
    A Session to use to restore the parameters.
saver : tf.train.Saver
"""

How do I use intersphinx to automatically link the object to the TensorFlow documentation?

Answer 1

UPDATE (30 MAY 2020): Github user "mr-ubik" has put together a package to autogenerate an objects.inv for the Python API (not JS, C++ or Java) of Tensorflow 2.0, which can be found here. The repository has both the objects.inv file itself and the tooling used to create it, as well as the intersphinx_mapping element to use in order to link it to your docs.

---

UPDATE (16 MAR 2021): Per a comment, STJ has continued development of the tooling for autogeneration of an objects.inv for Tensorflow in a fork at https://github.com/GPflow/tensorflow-intersphinx/. The inventory now targets TensorFlow v2.4 and includes TensorFlow Probability v0.12.

---

mzjn is right -- if the docs aren't Sphinx-generated, there won't be an objects.inv file to find.

You can, however, create your own objects.inv to go with Tensorflow. I authored a Python package to let me do this exact thing, along with how-to instructions. Briefly, and noting that some of the details here might not be fully correct:

1. Import sphobjinv and create an empty Inventory:

   >>> import sphobjinv as soi
   >>> inv = soi.Inventory()
   

2. Define the Sphinx header information:

   >>> inv.project = 'Tensorflow'
   >>> inv.version = '2.2'
   

3. Append sphobjinv.DataObjStr instances to the objects member of the Inventory for each object you wish to be included:

   >>> o = soi.DataObjStr(name='tf.autodiff', domain='py', role='module',
   ... priority='1', uri='python/tf/autodiff', dispname='-')
   >>> inv.objects.append(o)
   >>> print(inv)
   <Inventory (manual): foobar v1.5, 1 objects>
   

   {name} is usually the fully-qualified object name. The Python, C++, and Javascript portions of the docs can be handled by the default python, cpp, and js Sphinx domains, but you'd have to create your own Sphinx domain for Java. (The javasphinx project, which provided such a domain, has unfortunately been deprecated.) {role} will be whatever suitable directive applies for each object being documented (e.g., function, method, etc. for the py domain). {priority} affects how the objects in the inventory show up in the internal documentation search too, and should pretty much always just be 1 in a situation like this. The {relative uri} is relative to the base URI that you'll include in the intersphinx_mapping parameter in conf.py (see below). {displayname} is usually also the fully-qualified object name.

4. Generate and compress the inventory contents, and write to disk:

   >>> text = inv.data_file(contract=True)
   >>> ztext = soi.compress(text)
   >>> soi.writebytes('objects_tensorflow.inv', ztext)
   

5. Upload to a convenient, accessible location.

6. Configure intersphinx:

   intersphinx_mapping = {
       'tensorflow' = (
           'https://www.tensorflow.org/versions/r2.2/api_docs/',
           'uri/to/objects_tensorflow.inv',
       )
   }
   

And that should do it. It's a bit labor intensive, having to composite the file manually, but if you just add objects as you need them it shouldn't be too bad. Alternatively, you could scrape the documentation pageset and generate the inventory automatically (as was done by mr-ubik).