#!/usr/bin/env python
# coding: utf-8

# # 查阅文档
# 
# 受篇幅所限，本书无法对所有用到的PyTorch函数和类一一详细介绍。读者可以查阅相关文档来做更深入的了解。
# 
# ## 查找模块里的所有函数和类
# 
# 当我们想知道一个模块里面提供了哪些可以调用的函数和类的时候，可以使用`dir`函数。下面我们打印`torch.cuda`模块中所有的成员或属性。 
# 
# 
# *吐槽一下，原书这里用的是 `nd.random` 模块，而 PyTorch 的模块组织确实很烂，这里挑一个稍微有点条理的做示范*

# In[1]:


import torch

print(dir(torch.cuda))


# 通常我们可以忽略掉由`__`开头和结尾的函数（Python的特别对象）或者由`_`开头的函数（一般为内部函数）。通过其余成员的名字我们大致猜测出这个模块提供了各种对GPU的控制方法，包括可用设备数量（`device_count`）、GPU是否可用（`is_available`）、清空显存（`empty_cache`）等。
# 
# ## 查找特定函数和类的使用
# 
# 想了解某个函数或者类的具体用法时，可以使用`help`函数。让我们以`torch`中的`ones_like`函数为例，查阅它的用法。

# In[2]:


help(torch.ones_like)


# 从文档信息我们了解到，`ones_like`函数会创建和输入`Tensor`形状相同且元素为1的新`Tensor`。我们可以验证一下：

# In[3]:


x = torch.Tensor([[0, 0, 0], [2, 2, 2]])
y = torch.ones_like(x)
y


# 在Jupyter记事本里，我们可以使用`?`来将文档显示在另外一个窗口中。例如，使用`torch.rand?`将得到与`help(torch.rand)`几乎一样的内容，但会显示在额外窗口里。此外，如果使用`torch.rand??`，那么会额外显示该函数实现的代码。
# 
# 
# ## 在PyTorch网站上查阅
# 
# 读者也可以在PyTorch的网站上查阅相关文档。访问PyTorch网站 [https://pytorch.org/](https://pytorch.org/) （如图2.1所示），点击网页顶部的下拉菜单“Docs”可查阅各个前端语言的接口。此外，也可以在点击网页右上方的搜索图标直接搜索函数或类名称。
# 
# ![PyTorch官方网站](../img/pytorch-website.png)
# 
# 图2.2展示了PyTorch网站上有关`ones_like`函数的文档。
# 
# ![PyTorch网站上有关`ones_like`函数的文档](../img/ones_like.png)
# 
# ## 小结
# 
# * 遇到不熟悉的PyTorch API时，可以主动查阅它的相关文档。
# * 查阅PyTorch文档可以使用`dir`和`help`函数，或访问PyTorch官方网站。
# 
# 
# ## 练习
# 
# * 查阅`PyTorch`支持的其他操作。
# 
# 
# 
# 
# ## 扫码直达[讨论区](https://discuss.gluon.ai/t/topic/7116)
# 
# ![](../img/qr_lookup-api.svg)