Hi,
Changes introduced in [BEAM-2655
<https://github.com/apache/beam/pull/3613/files>] will make the pydoc tool
(sphinx) be stricter when checking cross references whenever a cross
reference is written.
Here are some examples with the type syntax highlighted in bold:
""" One line description
This is a cross reference to *:class:`~apache_beam.pvalue.PCollection`*
Note that the name has to be the absolute name of the identifier,
something like :class:`beam.PCollection` won't work.
Args:
pcoll (*~apache_beam.pvalue.PCollection*): Note that the argument type
does not require the :class:``, but any type within the description
have to be like *:class:`~apache_beam.pvalue.PCollection`*
Returns:
*~apache_beam.pvalue.PCollection*: The return type also does not require
the :class:``, but again, types within this description do require it.
Note the indentation for long lines in "Returns", it is indented to the
same level to where it is defined. It is different than the indentation
from "Args" and "Raises" since this is always one element, the other
sections are lists. If we don't follow this, it won't render correctly.
Raises:
*~exceptions.Exception*: These follow the same format as "Returns:". For
long lines, we have to further indent.
"""
David
