Re: [BuildStream] Updated CONTRIBUTING.rst guide

[Tristan Van Berkom <tristan vanberkom codethink co uk>]

Hi Angelos,

On Mon, 2018-10-08 at 14:00 -0400, Angelos Evripiotis wrote:
> Heya!
>
> Thanks for this, I think it’s super useful to have things laid out at
> this level of detail.

And thanks for the fixes in punctuation and grammar that you've been
providing :)

> I’m not sure if this thread is the appropriate place for this
> particular q, but let’s see.
>
> I was surprised that the Public API instance variable doc string
> works, as doc strings on variables are not a thing:
>
>   self.name = self._compute_name(context, element)
>   """The name of this foo
>
>   *Since: 1.2*
>   """

Yup, for example:

    https://buildstream.gitlab.io/buildstream/buildstream.plugin.html#buildstream.plugin.Plugin.name

> I think this is some sort of Sphinx magic. Please could a hint about
> how that works be included in the contributing guide if so, to save
> some time for dummies like me :)

I didn't realize at all that these were not considered valid docstrings
by Python natively. I've just added a `.. note::` in section you
mention above to highlight that they are indeed supported by sphinx.

Cheers,
    -Tristan