9

I'm using Sphinx to document my Python package. When I use the automodule directive on my module:

.. automodule:: mymodule
:members:

It prints everything including the GPL notice in the docstring. Is there any way to tell Sphinx to ignore the docstring/GPL or should I leave it included in the documentation?

JasonMArcher
  • 14,195
  • 22
  • 56
  • 52
tompreston
  • 630
  • 7
  • 24
  • 1
    some ideas 1) Don't put license to every file (too verbose anyway) 2) Use Python comments for license, not docstrings – Mikko Ohtamaa Jun 25 '13 at 19:22
  • 1
    The GPL license strongly suggests/requires the a copyright notice (with reference to a single license file) be included in each source file ([see here](https://softwareengineering.stackexchange.com/a/125842/243280)). – ryanjdillon Jul 24 '17 at 09:42
  • 1
    @MikkoOhtamaa It's recommended to put the GPL and a copyright notice in every file. The [Mozilla Public License](https://www.mozilla.org/en-US/MPL/) goes so far as to explicitly require it. – Daniel Shapero May 20 '18 at 01:30
  • @korrok Recommended by who? Recommended by why? I feel some people could argue that copy-pasting same piece of text to every file is little bit unnecessary copy-pasting. – Mikko Ohtamaa May 21 '18 at 08:12
  • 1
    @MikkoOhtamaa Good point, I should have clarified -- the [GNU project](https://www.gnu.org/licenses/gpl-howto.html) themselves recommend putting copyright and license notices in every file. See the section "Why license notices?" in that link. I think it's kind of silly to have to do this also, but I'm just repeating what the creators of the license recommend, not what I personally think would be sensible. – Daniel Shapero May 21 '18 at 15:08

1 Answers1

16

I ran into the same problem just now and fixed it by moving the license notice out of the docstring and into a regular comment block at the top of the file.

For example:

# Copyright 2013 Example, inc.  All rights reserved.
#
# License ...
# ...
# ...

""" This is the module docstring.

Description of the module here.

Etc, etc.

"""

import ....
...
David Pursehouse
  • 933
  • 6
  • 14