Skip to content

Commit

Permalink
Remove type annotations from signatures in html docs (pytorch#49294)
Browse files Browse the repository at this point in the history
Summary:
One unintended side effect of moving type annotations inline was that those annotations now show up in signatures in the html docs. This is more confusing and ugly than it is helpful. An example for `MaxPool1d`:

![image](https://user-images.githubusercontent.com/98330/102010280-77f86900-3d3d-11eb-8f83-e7ee0991ed92.png)

This makes the docs readable again. The parameter descriptions often already have type information, and there will be many cases where the type annotations will make little sense to the user (e.g., returning typevar T, long unions).

Change to `MaxPool1d` example:

![image](https://user-images.githubusercontent.com/98330/102010304-91011a00-3d3d-11eb-860d-ffa174b4d43b.png)

Note that once we can build the docs with Sphinx 3 (which is far off right now), we have two options to make better use of the extra type info in the annotations (some of which is useful):
- `autodoc_type_aliases`, so we can leave things like large unions unevaluated to keep things readable
- `autodoc_typehints = 'description'`, which moves the annotations into the parameter descriptions.

Another, more labour-intensive option, is what vadimkantorov suggested in pytorchgh-44964: show annotations on hover. Could also be done with some foldout, or other optional way to make things visible. Would be nice, but requires a Sphinx contribution or plugin first.

Pull Request resolved: pytorch#49294

Reviewed By: glaringlee

Differential Revision: D25535272

Pulled By: ezyang

fbshipit-source-id: 5017abfea941a7ae8c4595a0d2bdf8ae8965f0c4
  • Loading branch information
rgommers authored and facebook-github-bot committed Dec 14, 2020
1 parent 9e3c25f commit 6cfd7c3
Showing 1 changed file with 7 additions and 4 deletions.
11 changes: 7 additions & 4 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@
# TODO: verify this works as expected
release = 'master'

# Customized html_title here.
# Customized html_title here.
# Default is " ".join(project, release, "documentation") if not set
if RELEASE:
# remove hash (start with 'a') from version number if any
Expand Down Expand Up @@ -192,6 +192,9 @@
# Disable docstring inheritance
autodoc_inherit_docstrings = False

# Disable displaying type annotations, these can be very verbose
autodoc_typehints = 'none'


# -- katex javascript in header
#
Expand Down Expand Up @@ -253,9 +256,9 @@ def setup(app):
add_css(css_file)

# From PyTorch 1.5, we now use autogenerated files to document classes and
# functions. This breaks older references since
# functions. This breaks older references since
# https://docs.pytorch.org/torch.html#torch.flip
# moved to
# moved to
# https://docs.pytorch.org/torch/generated/torchflip.html
# which breaks older links from blog posts, stack overflow answers and more.
# To mitigate that, we add an id="torch.flip" in an appropriated place
Expand All @@ -278,7 +281,7 @@ def visit_reference(self, node):
# to autogenerated content
anchor = ref_anchor[1]
txt = node.parent.astext()
if txt == anchor or txt == anchor.split('.')[-1]:
if txt == anchor or txt == anchor.split('.')[-1]:
self.body.append('<p id="{}"/>'.format(ref_anchor[1]))
return old_call(self, node)
Klass.visit_reference = visit_reference
Expand Down

0 comments on commit 6cfd7c3

Please sign in to comment.