tensorflow - 如何在 Tensorflow 和 numpydoc 中使用 intersphinx？

Question

这里的主要问题是哪里(如果)有 objects.inv对于 TensorFlow，但是一个如何实际使用它的示例会很好。

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

"""
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)，可在 here 中找到.存储库有 objects.inv文件本身和用于创建它的工具，以及 intersphinx_mapping用于将其链接到您的文档的元素。

更新(2021 年 3 月 16 日):每一个 comment , STJ 继续开发用于自动生成 objects.inv 的工具。用于 https://github.com/GPflow/tensorflow-intersphinx/ 中叉中的 Tensorflow .该 list 现在针对 TensorFlow v2.4，包括 TensorFlow Probability v0.12。

mzjn is right -- 如果文档不是 Sphinx 生成的，则不会有 objects.inv要查找的文件。
但是，您可以创建自己的 objects.inv使用 Tensorflow。我编写了一个 Python 包来让我做这件事，还有 how-to instructions .简而言之，请注意这里的一些细节可能不完全正确:

进口 sphobjinv并创建一个空 Inventory :

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

定义Sphinx头信息:

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

追加 sphobjinv.DataObjStr实例到 objects Inventory成员(member)对于您希望包含的每个对象:

>>> 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 Sphinx 域，但您必须create your own Sphinx domain对于 Java。 (不幸的是，提供这样一个域的 javasphinx project 已被弃用。){role}将是适用于被记录的每个对象的任何合适的指令(例如， function 、 method 等适用于 py 域)。 {priority}也会影响库存中的对象在内部文档搜索中的显示方式，并且应该几乎总是1在这样的情况下。 {relative uri}相对于您将包含在 intersphinx_mapping 中的基本 URI conf.py 中的参数(见下文)。 {displayname}通常也是完全限定的对象名称。

生成并压缩 list 内容，并写入磁盘:

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

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

配置intersphinx:

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

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