From 69cf713596128f10f5e38762171225c6e26de296 Mon Sep 17 00:00:00 2001 From: Christian Herdtweck Date: Fri, 3 Aug 2018 15:28:09 +0200 Subject: [PATCH] Correct formatting of comments in template, add some more text --- templates/template.py | 38 ++++++++++++++++++++++++++------------ 1 files changed, 26 insertions(+), 12 deletions(-) diff --git a/templates/template.py b/templates/template.py index c139b7d..a15d052 100644 --- a/templates/template.py +++ b/templates/template.py @@ -24,20 +24,24 @@ Module name: Summary of this module Some overview over important classes and functions and such should be specified in this docstring, but please keep it brief! +This is rather long to show you useful spinx commenting options. Also mentions +some extra formatting rules we adhere to here. + +Each code file must have the license specified on top using hash-comments, +followed by a Copyright note with year and author. No need to specify author +inside code comments (except maybe for third-party contributions). + .. seealso:: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html -.. todo:: Do not forget to correct the codeauthor and license text commented by - hashes above. +.. todo:: Do not forget to update the year in Copyright note above .. note:: You should note this .. warning:: This is a warning - -.. codeauthor:: Intra2net """ from __future__ import print_function THE_CONSTANT = None -""" some constant with docstring *AFTER* the constant. Use this format! """ +"""Some constant with docstring *AFTER* the constant.""" ANOTHER_CONSTANT = 1 #: short docstring in same line -- note the #: @@ -48,22 +52,32 @@ THIRD_CONST = 3.333 class TestClass: """ - test class + Test class. + + Note how this comment consists of (almost) proper sentences, beginning with + an uppercase letter and ending with a period. + + Note also, that the starting and ending triple quotation marks get their + own lines and that there is no blank line after the comment is closed. That + is as it should be. - does nothing, really + Other than that, this class does nothing, really. """ def __init__(self, args): - """ constructor, gets its own paragraph in documentation + """ + Constructor, gets its own paragraph in documentation. :raises NotImplementedError: always """ raise NotImplementedError() def test_method(self, arg): - """ test method, does nothing + """ + Test method, does nothing. - for more doc string examples, see function :py:func:`send_message` + For more doc string examples, see function :py:func:`send_message`. + However, we might have more stringent formatting requirements here. :param arg: some argument :return: Nothing @@ -74,7 +88,8 @@ class TestClass: def send_message(sender, recipient, message_body, priority=1): - """ Send a message to a recipient + """ + Send a message to a recipient Example for a docstring that uses lots of reST fields, taken from http://sphinx-doc.org/domains.html @@ -98,5 +113,4 @@ def send_message(sender, recipient, message_body, priority=1): :raises TypeError: if the message_body is not a basestring :raises NotImplementedError: always """ - raise NotImplementedError() -- 1.7.1