Repository: pytorch
Issue: [docs] use sphinx link/reference checking features
Labels: module: docs,triaged,module: doc infra,better-engineering

## 📚 Documentation

### Motivation
Current stable docs has some dead links which are only known if we check manually or a user files an issue.
Some of those have been fixed in master docs.

### What can be done
We can automate this with sphinx link checking features (`make linkcheck` and nitpicky mode).
Change into `docs` and run `make help` will show like this
```
Sphinx v3.4.3
Please use `make target' where target is one of
  html        to make standalone HTML files
  dirhtml     to make HTML files named index.html in directories
  singlehtml  to make a single large HTML file
  pickle      to make pickle files
  json        to make JSON files
  htmlhelp    to make HTML files and an HTML help project
  qthelp      to make HTML files and a qthelp project
  devhelp     to make HTML files and a Devhelp project
  epub        to make an epub
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  latexpdf    to make LaTeX and PDF files (default pdflatex)
  latexpdfja  to make LaTeX files and run them through platex/dvipdfmx
  text        to make text files
  man         to make manual pages
  texinfo     to make Texinfo files
  info        to make Texinfo files and run them through makeinfo
  gettext     to make PO message catalogs
  changes     to make an overview of all changed/added/deprecated items
  xml         to make Docutils-native XML files
  pseudoxml   to make pseudoxml-XML files for display purposes
  linkcheck   to check all external links for integrity            <============================
  doctest     to run all doctests embedded in the documentation (if enabled)
  coverage    to run coverage check of the documentation (if enabled)
```

#### `linkcheck`
It is already integrated in sphinx, no extra extension needed.
What `make linkcheck` does is it uses `requests` to check the external links (like https://docs.python.org/3/library/random.html) return a valid response or not to make sure the docs doesn't include dead links.

[PyTorch-Ignite has already adopted it](https://github.com/pytorch/ignite/blob/8ccde27df71c0193fd2dd64bf21534fcb5a5b874/.github/workflows/docs.yml#L41-L60) and [Python itself has also using](https://devguide.python.org/docquality/?highlight=make%20linkcheck#developer-s-guide-workflow)

**How to use**: add `make linkcheck` in a docs building job in CI

#### `nitpicky`
Another feature is [`nitpicky` mode](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky).
What it does is it checks for internal references links are reachable or not (e.g, like `:ref:`, type annotations in docstring and return values)

[PyTorch-Ignite has already adopted it also](https://github.com/pytorch/ignite/blob/8ccde27df71c0193fd2dd64bf21534fcb5a5b874/docs/source/conf.py#L327-L341) and many famous python projects are using too.

**How to enable**: add `nitpicky=True` in `conf.py` and we are good to go.
NOTE : warnings will be shown up since the docs has some references missing. For some unreachable references, we can ignore them with [`nitpick_ignore`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpick_ignore).

**NOTE : It works without error in pure python projects. But I am not sure for a C++ and Python project tho.**



cc @ezyang @zou3519 @brianjo @mruberry