如何在 Tensorflow 和 numpydoc 中使用 intersphinx？

Question

这里的主要问题是哪里（如果）有objects.invTensorFlow 的，但是一个如何实际使用它的例子会很好。

例如，我目前有以下文档字符串：

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

如何使用 intersphinx 自动将对象链接到 TensorFlow 文档？

Answer 1

更新（2020 年 5 月 30 日）： Github 用户“mr-ubik”已将一个包放在一起，objects.inv用于为 Tensorflow 2.0的Python API（不是 JS、C++ 或 Java）自动生成一个包，可在此处找到。存储库具有objects.inv文件本身和用于创建它的工具，以及用于将其intersphinx_mapping链接到您的文档的元素。

更新（2021 年 3 月 16 日）：根据评论，STJ 继续开发objects.inv在https://github.com/GPflow/tensorflow-intersphinx/的 fork 中自动生成Tensorflow的工具。该清单现在针对 TensorFlow v2.4，包括 TensorFlow Probability v0.12。

mzjn 是对的——如果文档不是 Sphinx 生成的，就不会objects.inv找到文件。

但是，您可以创建自己的objects.inv以配合 Tensorflow。我编写了一个 Python 包来让我做这件事，以及操作说明。简而言之，请注意这里的一些细节可能不完全正确：

1. 导入sphobjinv并创建一个空的Inventory：

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

2. 定义Sphinx头信息：

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

3. 将sphobjinv.DataObjStr实例附加到您希望包含的每个对象的objects成员中Inventory：

   >>> 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}通常是完全限定的对象名称。该文档的Python和C ++，和Javascript部分可以由默认处理python，cpp和js狮身人面像域，但你必须创建自己的狮身人面像域名为Java。（该javasphinx项目，这提供了这样一个结构域，不幸被弃用。）{role}将是适用的任何合适的指令用于被记录的每个对象（例如，function，method等，为py域）。{priority}也会影响库存中的对象在内部文档搜索中的显示方式，并且应该几乎总是1处于这样的情况。的{relative uri}，你会包括在相对于基准URIintersphinx_mapping参数conf.py（见下文）。{displayname}通常也是完全限定的对象名称。

4. 生成并压缩清单内容，并写入磁盘：

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

5. 上传到方便、可访问的位置。

6. 配置intersphinx：

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

那应该这样做。这有点劳动密集型，必须手动合成文件，但如果您只是根据需要添加对象，那应该不会太糟糕。或者，您可以抓取文档页面集并自动生成清单（如 mr-ubik 所做的那样）。