On 7/15/19 3:25 PM, James Hartley wrote: > help(module_name) will place any text in the *first* module-level docstring > into the description section of the help page in Python 3.4.5. Subsequent > docstrings found at module level are ignored. > > I have been using this factoid for placement of a copyright & licensing > notice. By placing a rather lengthy copyright & license in the code in a > the second module-level docstring, it is prominent within the code, but not > cluttering up help() output. > > Two questions. Is there a more standardized way of including long license > descriptions in code, & is it documented that any other module-level > docstring will be ignored in help() output?
Rule #1: it's all opinion in the end... The common practice is that licence/copyright text is included as a comment in the code, not in a docstring. It's only a docstring if it's the first thing in its block, and that is assigned to the object's __doc__ attribute, and that's what help fishes out, so yes, that behavior is documented. Your second dosctring isn't technically a docstring, it's just a string, which isn't assigned to anything, so it just ends up getting lost as a runtime thing (no references). Is that what you want? You're on the right track in your second paragraph - "not cluttering up help output". There is _some_ support for this opinion, namely PEP 257 https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings The 4th, 5th and 6th paragraphs of that section all suggest what should be in the docstrings, none of them mentions copyright/license, all are oriented to making the help text usable by users. I'm sure someone else will have an opinion :) _______________________________________________ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor
