+1 to an example. In particular, are these inherited members grouped in such a way that it makes it easy to ignore them once they get to "low" in the stack? If it can't be per-module, is there a "nice" set of ancestors to avoid (as it seems this option takes such an argument).
On Wed, Mar 31, 2021 at 4:23 PM Pablo Estrada <pabl...@google.com> wrote: > Do you have an example of what it would look like when released? > > On Wed, Mar 31, 2021 at 4:16 PM Brian Hulette <bhule...@google.com> wrote: > >> I'm working on generating useful API docs for the DataFrame API >> (BEAM-12074). In doing so, one thing I've found would be very helpful is if >> we could include docstrings for inherited members in the API docs. That way >> docstrings for operations defined in DeferredDataFrameOrSeries [1], will be >> propagated to DeferredDataFrame [2] and DeferredSeries, and the former can >> be hidden entirely. This would be more consistent with the pandas >> documentation [3]. >> >> It looks like we can do this by specifying :inherited-members: [4], but >> this will apply to _all_ of our API docs, there doesn't seem to be a way to >> restrict it to a particular module. This seems generally useful to me, but >> it would be a significant change, so I wanted to see if there are any >> objections from dev@ before doing this. >> >> An example of the kind of change this would produce: any PTransform >> sub-classes, e.g. CombinePerKey [5], would now include docstrings for every >> PTransform member, e.g. with_input_types [6], and display_data [7]. >> >> Would there be any objections to that? >> >> Thanks, >> Brian >> >> [1] >> https://beam.apache.org/releases/pydoc/2.27.0/apache_beam.dataframe.frames.html#apache_beam.dataframe.frames.DeferredDataFrameOrSeries >> [2] >> https://beam.apache.org/releases/pydoc/2.27.0/apache_beam.dataframe.frames.html#apache_beam.dataframe.frames.DeferredDataFrame >> [3] https://pandas.pydata.org/docs/reference/frame.html >> [4] https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html >> [5] >> https://beam.apache.org/releases/pydoc/2.27.0/apache_beam.transforms.core.html?highlight=combineperkey#apache_beam.transforms.core.CombinePerKey >> [6] >> https://beam.apache.org/releases/pydoc/2.27.0/apache_beam.transforms.ptransform.html#apache_beam.transforms.ptransform.PTransform.with_input_types >> [7] >> https://beam.apache.org/releases/pydoc/2.27.0/apache_beam.transforms.display.html#apache_beam.transforms.display.HasDisplayData.display_data >> >
