* Python docstrings and licensing/authorship
@ 2020-09-16 15:47 John Snow
2020-09-16 16:05 ` Christophe de Dinechin
0 siblings, 1 reply; 6+ messages in thread
From: John Snow @ 2020-09-16 15:47 UTC (permalink / raw)
To: QEMU Developers
For some of the Python cleanup work I am doing, I am moving preamble
comments into docstrings. These docstrings are visible in interactive
editors and may be visible when using Sphinx to generate documentation
manuals for Python code.
My instinct is to remove the licensing and authorship information from
the preamble and leave the docstring only with information functionally
relevant to the module, while leaving licensing and authorship
information in a comment (above? below?).
The end effect would be that using e.g. `help(qapi.parser)` in the
interactive Python shell would not show licensing or copyright for the
module, but it would still be visible in the source file, as always.
Is this in bad taste? Do we have strong feelings about authorship and
licensing being visible in help output and generated documentation?
--js
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Python docstrings and licensing/authorship
2020-09-16 15:47 Python docstrings and licensing/authorship John Snow
@ 2020-09-16 16:05 ` Christophe de Dinechin
2020-09-16 16:22 ` John Snow
0 siblings, 1 reply; 6+ messages in thread
From: Christophe de Dinechin @ 2020-09-16 16:05 UTC (permalink / raw)
To: John Snow; +Cc: QEMU Developers
> On 16 Sep 2020, at 17:47, John Snow <jsnow@redhat.com> wrote:
>
> For some of the Python cleanup work I am doing, I am moving preamble comments into docstrings. These docstrings are visible in interactive editors and may be visible when using Sphinx to generate documentation manuals for Python code.
>
> My instinct is to remove the licensing and authorship information from the preamble and leave the docstring only with information functionally relevant to the module, while leaving licensing and authorship information in a comment (above? below?).
>
> The end effect would be that using e.g. `help(qapi.parser)` in the interactive Python shell would not show licensing or copyright for the module, but it would still be visible in the source file, as always.
>
> Is this in bad taste? Do we have strong feelings about authorship and licensing being visible in help output and generated documentation?
What about putting that in a separate pseudo-entity, so that help(copyright) would show it?
>
> --js
>
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Python docstrings and licensing/authorship
2020-09-16 16:05 ` Christophe de Dinechin
@ 2020-09-16 16:22 ` John Snow
2020-09-16 16:37 ` Daniel P. Berrangé
0 siblings, 1 reply; 6+ messages in thread
From: John Snow @ 2020-09-16 16:22 UTC (permalink / raw)
To: Christophe de Dinechin; +Cc: QEMU Developers
On 9/16/20 12:05 PM, Christophe de Dinechin wrote:
>
>
>> On 16 Sep 2020, at 17:47, John Snow <jsnow@redhat.com> wrote:
>>
>> For some of the Python cleanup work I am doing, I am moving preamble comments into docstrings. These docstrings are visible in interactive editors and may be visible when using Sphinx to generate documentation manuals for Python code.
>>
>> My instinct is to remove the licensing and authorship information from the preamble and leave the docstring only with information functionally relevant to the module, while leaving licensing and authorship information in a comment (above? below?).
>>
>> The end effect would be that using e.g. `help(qapi.parser)` in the interactive Python shell would not show licensing or copyright for the module, but it would still be visible in the source file, as always.
>>
>> Is this in bad taste? Do we have strong feelings about authorship and licensing being visible in help output and generated documentation?
>
> What about putting that in a separate pseudo-entity, so that help(copyright) would show it?
>
help is a Python builtin that shows metadata about an object. If an
object has a docstring, it is capable of displaying that as part of the
help output. I'm not sure what type you are suggesting `copyright` to be.
So, you could do something like:
__copyright__ == """
Copyright (C) 2020 John Snow, for Red Hat Inc.
"""
And you could then theoretically do:
>>> import qapi
>>> qapi.__copyright__
which will show you that information. However, I don't think there's any
standard for module-level metadata like this, so the odds of this
information being seen or used is low.
Python has some standards for package-level metadata, but I don't think
there are any standards for module-level metadata *except* the __doc__
attribute -- which is where the module-level docstring goes when we
write one.
The real question I have is if anyone thinks it would be "rude" to
separate out any of the comment preambles (currently not visible at
runtime or docs in any way, shape or form!) into two pieces:
1. Functional stuff relating to the usage of the module, visible in
help(module_name), visible in generated docs, visible in IDE popups, etc.
2. Authorship/copyright and licensing info, not visible in the above places.
>>
>> --js
>>
>>
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Python docstrings and licensing/authorship
2020-09-16 16:22 ` John Snow
@ 2020-09-16 16:37 ` Daniel P. Berrangé
2020-09-17 12:55 ` Markus Armbruster
0 siblings, 1 reply; 6+ messages in thread
From: Daniel P. Berrangé @ 2020-09-16 16:37 UTC (permalink / raw)
To: John Snow; +Cc: Christophe de Dinechin, QEMU Developers
On Wed, Sep 16, 2020 at 12:22:37PM -0400, John Snow wrote:
> On 9/16/20 12:05 PM, Christophe de Dinechin wrote:
> >
> >
> > > On 16 Sep 2020, at 17:47, John Snow <jsnow@redhat.com> wrote:
> > >
> > > For some of the Python cleanup work I am doing, I am moving preamble comments into docstrings. These docstrings are visible in interactive editors and may be visible when using Sphinx to generate documentation manuals for Python code.
> > >
> > > My instinct is to remove the licensing and authorship information from the preamble and leave the docstring only with information functionally relevant to the module, while leaving licensing and authorship information in a comment (above? below?).
> > >
> > > The end effect would be that using e.g. `help(qapi.parser)` in the interactive Python shell would not show licensing or copyright for the module, but it would still be visible in the source file, as always.
> > >
> > > Is this in bad taste? Do we have strong feelings about authorship and licensing being visible in help output and generated documentation?
> >
> > What about putting that in a separate pseudo-entity, so that help(copyright) would show it?
> >
>
> help is a Python builtin that shows metadata about an object. If an object
> has a docstring, it is capable of displaying that as part of the help
> output. I'm not sure what type you are suggesting `copyright` to be.
>
> So, you could do something like:
>
> __copyright__ == """
> Copyright (C) 2020 John Snow, for Red Hat Inc.
> """
>
> And you could then theoretically do:
>
> >>> import qapi
> >>> qapi.__copyright__
>
> which will show you that information. However, I don't think there's any
> standard for module-level metadata like this, so the odds of this
> information being seen or used is low.
>
> Python has some standards for package-level metadata, but I don't think
> there are any standards for module-level metadata *except* the __doc__
> attribute -- which is where the module-level docstring goes when we write
> one.
>
> The real question I have is if anyone thinks it would be "rude" to separate
> out any of the comment preambles (currently not visible at runtime or docs
> in any way, shape or form!) into two pieces:
>
> 1. Functional stuff relating to the usage of the module, visible in
> help(module_name), visible in generated docs, visible in IDE popups, etc.
>
> 2. Authorship/copyright and licensing info, not visible in the above places.
I think this makes sense. IME it is not common to include copyright /
author info the module help text, as that s non-technical information.
Including author info in API docs in particular I think is liable to
be harmful becuase it will encourage users to directly email
individual authors for help, rather than using collective comms
channels like the mailing lists or forum or bug tracker.
And of course all of this author and copyright info is generally
horribly out of date, as people rarely add themselves when modifying
existing files.
As long as you don't remove the copyright info entirely, that satisfies
the license requirements to preserve copyright notices.
Regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Python docstrings and licensing/authorship
2020-09-16 16:37 ` Daniel P. Berrangé
@ 2020-09-17 12:55 ` Markus Armbruster
2020-09-17 19:02 ` John Snow
0 siblings, 1 reply; 6+ messages in thread
From: Markus Armbruster @ 2020-09-17 12:55 UTC (permalink / raw)
To: Daniel P. Berrangé
Cc: John Snow, Christophe de Dinechin, QEMU Developers
Daniel P. Berrangé <berrange@redhat.com> writes:
> On Wed, Sep 16, 2020 at 12:22:37PM -0400, John Snow wrote:
[...]
>> The real question I have is if anyone thinks it would be "rude" to separate
>> out any of the comment preambles (currently not visible at runtime or docs
>> in any way, shape or form!) into two pieces:
>>
>> 1. Functional stuff relating to the usage of the module, visible in
>> help(module_name), visible in generated docs, visible in IDE popups, etc.
>>
>> 2. Authorship/copyright and licensing info, not visible in the above places.
>
> I think this makes sense. IME it is not common to include copyright /
> author info the module help text, as that s non-technical information.
Seconded.
[...]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Python docstrings and licensing/authorship
2020-09-17 12:55 ` Markus Armbruster
@ 2020-09-17 19:02 ` John Snow
0 siblings, 0 replies; 6+ messages in thread
From: John Snow @ 2020-09-17 19:02 UTC (permalink / raw)
To: Markus Armbruster, Daniel P. Berrangé
Cc: Christophe de Dinechin, QEMU Developers
On 9/17/20 8:55 AM, Markus Armbruster wrote:
> Daniel P. Berrangé <berrange@redhat.com> writes:
>
>> On Wed, Sep 16, 2020 at 12:22:37PM -0400, John Snow wrote:
> [...]
>>> The real question I have is if anyone thinks it would be "rude" to separate
>>> out any of the comment preambles (currently not visible at runtime or docs
>>> in any way, shape or form!) into two pieces:
>>>
>>> 1. Functional stuff relating to the usage of the module, visible in
>>> help(module_name), visible in generated docs, visible in IDE popups, etc.
>>>
>>> 2. Authorship/copyright and licensing info, not visible in the above places.
>>
>> I think this makes sense. IME it is not common to include copyright /
>> author info the module help text, as that s non-technical information.
>
> Seconded.
>
*slams gavel*
That's consensus, folks! Thanks.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-09-17 19:06 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-09-16 15:47 Python docstrings and licensing/authorship John Snow
2020-09-16 16:05 ` Christophe de Dinechin
2020-09-16 16:22 ` John Snow
2020-09-16 16:37 ` Daniel P. Berrangé
2020-09-17 12:55 ` Markus Armbruster
2020-09-17 19:02 ` John Snow
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).