Use this rather than #15980 . cc: @ezyang

Hi @zasdfgbnm, I was getting ready to merge your patch, but I realized there might be a better and more way to pull out the list of documented identifiers. Basically, instead of groveling through _torch_docs.py to find docs, instead we should just iterate over all identifiers in torch module, and count those with non-empty docstrings as being documented. What do you think? Should save us a lot of code here, and will also work for functions which are directly defined in the file rather than through _add_docstr

@ezyang I just did some experiment, but I still think including only _tensor_docs.py and torch.functional is a better choice.

import torch
import ast
import _ast
import re
import matplotlib.pyplot as plt
from matplotlib_venn import venn3

# copied from PR
r1 = re.compile(r'\.\. autofunction:: (\w*)')
everything = set()
filename = '/home/gaoxiang/pytorch/docs/source/torch.rst'
with open(filename, 'r') as f:
    lines = f.readlines()
    for l in lines:
        l = l.strip()
        name = r1.findall(l)
        if name:
            everything.add(name[0])


pypath = '/home/gaoxiang/pytorch/torch/_torch_docs.py'
everything2 = set()
with open(pypath, 'r') as f:
    body = ast.parse(f.read()).body
    for i in body:
        if not isinstance(i, _ast.Expr):
            continue
        i = i.value
        if not isinstance(i, _ast.Call):
            continue
        if i.func.id != 'add_docstr':
            continue
        i = i.args[0]
        if i.value.id != 'torch':
            continue
        i = i.attr
        everything2.add(i)
    for p in dir(torch.functional):
        if not p.startswith('_') and p[0].islower():
            everything2.add(p)

# all attr in torch with nonempty docstring
alltorch = set(a for a in dir(torch) if getattr(torch, a).__doc__ and not a.startswith('_'))

fig = plt.figure(figsize=(20, 20))
v = venn3(
    [alltorch, everything, everything2],
    set_labels = ('torch.*', 'torch.rst', '_torch_docs and functional'),
    set_colors=('r', 'g', 'b'),
    alpha=0.8)
plt.show()

print(len(alltorch))
print(len(everything))
print(len(everything2))
print()

print(alltorch - everything2)

The Venn diagram is below, read is torch.*, green is torch.rst and blue is _torch_docs and functional. green and blue has better match.

The print is:

244
208
199

{'threshold_', 'pdist', 'fork', 'os', 'rrelu_', 'has_lapack', 'optim', 'conv1d', 'enable_grad', 'potrs', 'register_batch_operator', 'set_grad_enabled', 'set_default_dtype', 'has_mkl', 'cosine_similarity', 'has_cudnn', 'name', 'relu_', 'adaptive_avg_pool1d', 'conv_transpose2d', 'cuda', 'celu_', 'to_batch_graph', 'testing', 'load', 'conv3d', 'save', 'selu_', 'wait', 'set_rng_state', 'set_default_tensor_type', 'merge_type_from_type_comment', 'multiprocessing', 'conv_transpose1d', 'pixel_shuffle', 'is_storage', 'sys', 'platform', 'conv_tbc', 'is_tensor', 'autograd', 'initial_seed', 'distributions', 'compiled_with_cxx11_abi', 'conv_transpose3d', 'avg_pool1d', 'set_printoptions', 'no_grad', 'import_ir_module_from_buffer', 'import_ir_module', 'manual_seed', 'conv2d', 'parse_type_comment', 'get_rng_state'}

we can see things in torch but not in _torch_docs and functional are mainly internal functions, things documented somewhere else, imported modules and those ops that should be in nn.functional rather than torch.

I guess the question is what the motivation of this test is.

1. If the motivation is to ensure everything that is explicitly documented in _torch_docs.py is also mentioned in the rst file, this patch as stands is great!
2. If the motivation is to ensure everything in torch is documented, the alternate mechanism is better.

Still, doing (1) seems like a good step on the way to (2), so we can take this as is.

@ezyang I just updated the whitelist to add a new symbol attonate introduced in master.

@ezyang #16057 is the followup of this testing tensor methods.