[ZODB-Dev] [Checkins] SVN: ZODB/trunk/src/persistent/wref.pyMerged the rst formatting to the trunk

[Christophe Combelles]

On Mon, 13 Oct 2008 08:32:52 +0200, Wichert Akkerman <wichert at wiggy.net>
wrote:
> Christophe Combelles wrote:
>> Zvezdan Petkovic a écrit :
>>> On Oct 12, 2008, at 5:51 AM, Christophe Combelles wrote:
>>>
>>>> Log message for revision 92067:
>>>>  Merged the rst formatting to the trunk
>>> ...
>>>
>>>>     Here's an example. We'll start by creating a persistent object and
>>>> -    a refernce to it:
>>>> +    a reference to it::
>>>>
>>>> -    >>> import persistent.list
>>>> -    >>> import ZODB.tests.util
>>>> -    >>> ob = persistent.list.PersistentList()
>>>> -    >>> ref = WeakRef(ob)
>>>> -    >>> ref() is ob
>>>> -    True
>>>> +        >>> import persistent.list
>>>> +        >>> import ZODB.tests.util
>>>> +        >>> ob = persistent.list.PersistentList()
>>>> +        >>> ref = WeakRef(ob)
>>>> +        >>> ref() is ob
>>>> +        True
>>> Why have these changes been made?
>>> This is now an invalid reST.
>>>
>>> The reST specification clearly states the difference between a literal 
> 
>>> block (started with ::) and a doctest block.
>>>
>>> Please see the examples in the section "Doctest blocks" of the  
>>> specification at
>>>
>>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
>>>
>>> At the bottom of that section is also stated.
>>>
>>> 	"Indentation is not required for doctest blocks."
>>>
>>> Yes, they can be indented, but there is absolutely no need to change a 
> 
>>> perfectly valid reST only to introduce a whitespace change in SVN and  
>>> a wrong literal block use.
>>>
>>> Can we, please, refrain from such changes in the future unless we are  
>>> absolutely certain that the changes are better than the original?
>>>
>>> This should be reverted.
>> 
>> 
>> The only reason I did this is for readability in the APIDOC.
> 
> I would suggest that the better change is to fix apidoc.


I've finally found that it is still OK in the apidoc if I revert all
indenting, but I only keep the __docformat__="restructuredtext"
Are you ok to keep just this change?

Christophe


> 
> Wichert.
> 
> 
>