[Doc-SIG] Python docs in reST

[Ian Bicking]

Martin Blais wrote:
> On 5/18/05, Ian Bicking <ianb at colorstudy.com> wrote:
>>But I have a lot of middling documentation.  It's not doctestable, it's
>>not structured so that an interface is useful, the code is in modules I
>>don't expect the user to import specifically, and I am wary of just
>>creating a separate text file because of API drift; I've found it hard
>>to keep track of the information in two places.
> 
> 
> i'm going to sound like a sucker here, but why not just put it "next"
> to the module file, in a .txt file?, e.g.
> 
>   module.py
>   module.txt
> 
> won't hurt the code, and it's right there a C-xC-f away...  (I don't
> like to have docs there somehow (and i suppose you don't either
> because nobody does it), but i really cannot say why...)

I don't know why either, but somehow it seems Wrong.  Because it breaks 
tab completion?  Because it's annoying to use with distutils?  Eh, those 
probably aren't the reasons.

In part I guess it's because I like docstrings.  I don't want to leave 
my module bare because it's all in a separate .txt file.  And I 
definitely don't want to duplicate the documentation in both places.  At 
the same time, I also want people to be able to read docs without 
browsing through the source, and people look in docs/ first for that 
stuff.  And there are docs that definitely don't belong besides the source.

-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org