Path: csiph.com!usenet.pasdenom.info!weretis.net!feeder4.news.weretis.net!ecngs!feeder2.ecngs.de!novso.com!newsfeed.xs4all.nl!newsfeed6.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail Return-Path: X-Original-To: python-list@python.org Delivered-To: python-list@mail.python.org X-Spam-Status: OK 0.001 X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'url:pypi': 0.03; 'processed': 0.05; 'sphinx': 0.07; 'api': 0.09; 'python': 0.09; 'docstrings': 0.09; 'lawrence': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'underlying': 0.09; 'url:sphinx': 0.09; 'subject:python': 0.11; 'kern': 0.16; 'programmers,': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'scientists': 0.16; 'sphinx.': 0.16; 'subject:their': 0.16; 'wow,': 0.16; 'martin': 0.16; 'users.': 0.16; 'wrote:': 0.17; 'community,': 0.17; 'documented': 0.17; 'tend': 0.17; 'thorough': 0.17; 'creates': 0.18; '>>>': 0.18; 'interpret': 0.22; 'ourselves': 0.23; "i've": 0.23; 'external': 0.24; 'header:In- Reply-To:1': 0.25; 'header:User-Agent:1': 0.26; 'developers': 0.26; 'am,': 0.27; 'guess': 0.27; 'document.': 0.27; 'important.': 0.27; 'header:X-Complaints-To:1': 0.28; 'lines': 0.28; 'environment': 0.29; 'source': 0.29; "i'm": 0.29; 'classes': 0.30; 'expect': 0.31; 'url:python': 0.32; 'to:addr:python-list': 0.33; 'typically': 0.33; 'robert': 0.35; 'received:org': 0.36; 'url:org': 0.36; 'smaller': 0.36; 'too': 0.36; 'far': 0.37; 'data': 0.37; 'subject:: ': 0.38; 'mark': 0.38; 'url:docs': 0.38; 'to:addr:python.org': 0.39; 'build': 0.39; 'header:Received:5': 0.40; 'end': 0.40; 'think': 0.40; 'url:index': 0.61; 'different': 0.63; 'world': 0.63; 'ever': 0.63; 'details': 0.63; 'our': 0.65; 'detail.': 0.65; 'frequently': 0.65; 'url:0': 0.67; 'believe': 0.69; 'analysis': 0.70; 'eco': 0.84; 'otten': 0.84; 'terrible': 0.84; 'thorough,': 0.84; 'url:reference': 0.84 X-Injected-Via-Gmane: http://gmane.org/ To: python-list@python.org From: Robert Kern Subject: Re: Organisation of python classes and their methods Date: Fri, 02 Nov 2012 10:55:06 +0000 References: <7xa9v0wj2g.fsf@ruckus.brouhaha.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Gmane-NNTP-Posting-Host: 213.1.240.227 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:16.0) Gecko/20121026 Thunderbird/16.0.2 In-Reply-To: X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: General discussion list for the Python programming language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 42 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1351853725 news.xs4all.nl 6926 [2001:888:2000:d::a6]:58578 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:32618 On 11/2/12 10:21 AM, Peter Otten wrote: > Martin Hewitson wrote: > >> On 2, Nov, 2012, at 09:40 AM, Mark Lawrence >> wrote: > >>> 20 lines of documentation per method? As far as I'm concerned that's not >>> a smell, that's a stink. >> >> Wow, I don't think I've ever been criticised before for writing too much >> documentation :) >> >> I guess we have different end users. This is not a set of classes for >> other developers to use: it's a set of classes which creates a data >> analysis environment for scientists to use. They are not programmers, and >> expect the algorithms to be documented in detail. > > While I would never discourage thorough documentation you may be better off > with smaller docstrings and the details in an external document. Python > projects typically use rst-files processed by sphinx. > > http://pypi.python.org/pypi/Sphinx/ In the science/math community, we tend to build the Sphinx API reference from the thorough, authoritative docstrings. We like having complete docstrings because we are frequently at the interactive prompt. We tend to have broad APIs, so having a single source of documentation and not repeating ourselves is important. http://docs.scipy.org/doc/numpy/reference/index.html http://docs.scipy.org/doc/scipy/reference/index.html http://www.sagemath.org/doc/reference/ http://docs.sympy.org/0.7.2/modules/index.html http://scikit-learn.org/stable/modules/classes.html -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco