[DOC] Use type hints to show annotation in the docs

[ShawnZhong]

Fixes #44964

Use type hints in the code to show type annotations in the parameters section of the docs.

For the parameters already documented in the docstring, but lack the type annotation, the type hints from the code are used:

Before	After

Before	After

Ref:

• PR Remove type annotations from signatures in html docs #49294 removed type annotations from signatures in HTML docs.
• Sphinx version was bumped to 5.0.0 in PR Docs: build with Sphinx 5 #70309
• Duplicated (closed) issues: Show parameter types in function signatures #78311 and Use type hints (PEP 484) in generated documentation #77501

[facebook-github-bot]

🔗 Helpful links

• 🧪  See artifacts and rendered test results at hud.pytorch.org/pr/79086
• 📄  Preview Python docs built from this PR
• 📄  Preview C++ docs built from this PR
• ❓Need help or want to give feedback on the CI? Visit our office hours

❌ 1 New Failures, 1 Pending

As of commit 4e4a735308 (more details on the Dr. CI page):

Expand to see more

---

• 1/1 failures introduced in this PR

---

🕵️ 1 new failure recognized by patterns

The following CI failures do not appear to be due to upstream breakages

pull / linux-focal-py3.7-gcc7 / test (backwards_compat, 1, 1, linux.2xlarge) (1/1)

Step: "Test" (full log | diagnosis details | 🔁 rerun)

2022-06-09T22:39:10.2484735Z The PR is introduc...m to confirm whether this change is wanted or not.

2022-06-09T22:39:10.2471728Z processing existing schema:  text(__torch__.torch.classes.profiling.SourceRef _0) -> str _0
2022-06-09T22:39:10.2472804Z processing existing schema:  count(__torch__.torch.classes.profiling.InstructionStats _0) -> int _0
2022-06-09T22:39:10.2474074Z processing existing schema:  duration_ns(__torch__.torch.classes.profiling.InstructionStats _0) -> int _0
2022-06-09T22:39:10.2475414Z processing existing schema:  source(__torch__.torch.classes.profiling.SourceStats _0) -> __torch__.torch.classes.profiling.SourceRef _0
2022-06-09T22:39:10.2477281Z processing existing schema:  line_map(__torch__.torch.classes.profiling.SourceStats _0) -> Dict(int, __torch__.torch.classes.profiling.InstructionStats) _0
2022-06-09T22:39:10.2478257Z processing existing schema:  __init__(__torch__.torch.classes.profiling._ScriptProfile _0) -> NoneType _0
2022-06-09T22:39:10.2479581Z processing existing schema:  enable(__torch__.torch.classes.profiling._ScriptProfile _0) -> NoneType _0
2022-06-09T22:39:10.2480822Z processing existing schema:  disable(__torch__.torch.classes.profiling._ScriptProfile _0) -> NoneType _0
2022-06-09T22:39:10.2482744Z processing existing schema:  _dump_stats(__torch__.torch.classes.profiling._ScriptProfile _0) -> __torch__.torch.classes.profiling.SourceStats[] _0
2022-06-09T22:39:10.2484276Z processing existing schema:  __init__(__torch__.torch.classes.dist_rpc.WorkerInfo _0, str _1, int _2) -> NoneType _0
2022-06-09T22:39:10.2484735Z The PR is introducing backward incompatible changes to the operator library. Please contact PyTorch team to confirm whether this change is wanted or not. 
2022-06-09T22:39:10.2484747Z 
2022-06-09T22:39:10.2484887Z Broken ops: [
2022-06-09T22:39:10.2485205Z 	aten::linalg_lu_solve(Tensor LU, Tensor pivots, Tensor B, *, bool left=True, bool adjoint=False) -> Tensor
2022-06-09T22:39:10.2485603Z 	aten::linalg_lu_solve.out(Tensor LU, Tensor pivots, Tensor B, *, bool left=True, bool adjoint=False, Tensor(a!) out) -> Tensor(a!)
2022-06-09T22:39:10.2485666Z ]
2022-06-09T22:39:10.3652677Z + cleanup
2022-06-09T22:39:10.3652807Z + retcode=1
2022-06-09T22:39:10.3652927Z + set +x
2022-06-09T22:39:10.3691117Z ##[error]Process completed with exit code 1.
2022-06-09T22:39:10.3728304Z ##[group]Run pytorch/pytorch/.github/actions/get-workflow-job-id@master

---

This comment was automatically generated by Dr. CI (expand for details).

Please report bugs/suggestions to the (internal) Dr. CI Users group.

Click here to manually regenerate this comment.

[rgommers]

Thanks for working on this @ShawnZhong!

CI isn't being all that helpful here just yet it looks like:

There's a lot of CI failures though, the first one I looked at contained:

...
File "/opt/conda/lib/python3.7/site-packages/torch/jit/annotations.py", line 408, in ann_to_type
    raise ValueError(f"Unknown type annotation: '{ann}' at {loc.highlight()}")
ValueError: Unknown type annotation: 'Tensor' at 

so as happens more often, there may be a conflict between what Mypy/Sphinx wants and what the PyTorch JIT can actually understand.

[ShawnZhong]

Yep. It seems that there is some issue with postponed annotations (PEP 563) and JIT. I'm trying to fix them in a separate PR: #79096. If the JIT issue cannot be easily fixed, I might leave this PR without autodoc_type_aliases.

For future reference, the current commit is 646b745 and one error message is available at https://github.com/pytorch/pytorch/runs/6784944582?check_suite_focus=true.

[albanD]

You can ignore the backward compat test failure as it is a master breakage.

[albanD]

The change sounds ok to me.
Do we want to merge this without the autodoc_type_aliases as it is an improvement already?

Do we have any way to check which part of the doc this is changing to make sure it all behaves well? Or we can just spot check some functions?

cc @svekars

[github-actions]

Looks like this PR hasn't been updated in a while so we're going to go ahead and mark this as Stale.
Feel free to remove the Stale label if you feel this was a mistake.
If you are unable to remove the Stale label please contact a maintainer in order to do so.
If you want the bot to never mark this PR stale again, add the no-stale label.
Stale pull requests will automatically be closed after 30 days of inactivity.

[justinchuby]

@albanD can we include this for the new release, as this greatly improve the documentation reading experience?

[justinchuby]

Taking the liberty to add it to the milestone. Please feel free to change

[albanD]

Hey!
Could you rebase this on top of latest master? Make sure all CI passes and the generated doc looks good?

[justinchuby]

@ShawnZhong thanks!

[facebook-github-bot]

/easycla

As part of the transition to the PyTorch Foundation, this project now requires contributions be covered under the new CLA. See #85559 for additional details.

This comment will trigger a new check of this PR. If you are already covered, you will simply see a new "EasyCLA" check that passes. If you are not covered, a bot will leave a new comment with a link to sign.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: ShawnZhong / name: Shawn Zhong (a33365a)

[pytorch-bot]

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/79086

• 📄 Preview Python docs built from this PR
• 📄 Preview C++ docs built from this PR
• ❓ Need help or want to give feedback on the CI? Visit our office hours

Note: Links to docs will display an error until the docs builds have been completed.

✅ No Failures, 2 Pending

As of commit a33365a:
💚 Looks good so far! There are no failures yet. 💚

This comment was automatically generated by Dr. CI and updates every 15 minutes.

[ShawnZhong]

Just rebased the branch to the latest master. I went over some generated docs, and they look good to me. Something worth noting:

• If Sphinx cannot find the source location, it cannot infer the type hints. That's why torch.nn.AvgPool1d has the type annotation added but torch.nn.functional.avg_pool1d does not.

• Sphinx adds a return type section to the docs if the return type can be obtained from hints (e.g., torch.initial_seed, torch.distributed.get_backend). Not sure if that's really needed, but I couldn't find a way to disable that either.

[ShawnZhong]

Any updates on the review?

[justinchuby]

@albanD bump

[malfet]

@pytorchbot merge -f "This is just a doc config update"

[pytorchmergebot]

Merge started

Your change will be merged immediately since you used the force (-f) flag, bypassing any CI checks (ETA: 1-5 minutes).

Learn more about merging in the wiki.

Questions? Feedback? Please reach out to the PyTorch DevX Team

Advanced Debugging

Check the merge workflow status
here

[github-actions]

Hey @ShawnZhong.
You've committed this PR, but it does not have both a 'release notes: ...' and 'topics: ...' label. Please add one of each to the PR. The 'release notes: ...' label should represent the part of PyTorch that this PR changes (fx, autograd, distributed, etc) and the 'topics: ...' label should represent the kind of PR it is (not user facing, new feature, bug fix, perf improvement, etc). The list of valid labels can be found here for the 'release notes: ...' and here for the 'topics: ...'.
For changes that are 'topic: not user facing' there is no need for a release notes label.