Thank you David. I think this is a good proposal and will make docs better for users. We should note that, python developers will need to follow these guidelines. In order to make it easier, I would suggest looking for ways to simplify things (like the one Cham suggested or as you suggested in the PR to have plugins to make things simpler) and I would also recommend documenting these guidelines in the contribution guide.
Ahmet On Fri, Aug 4, 2017 at 4:07 PM, Chamikara Jayalath <[email protected]> wrote: > 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 > > >
