Hi David, This is great. Thanks for making our docs better.
Looking at your PR, seems like we can either do :class:`~apache_beam.pvalue.PCollection` or ``PCollection`` for highlighting, right ? In Java I think people usually give the link for the first reference in long doc comments and just highlight for the remaining occurrences. Should we follow a similar pattern for Python ? Thanks, Cham On Fri, Aug 4, 2017 at 12:10 PM David Cavazos <[email protected]> wrote: > 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 >
