[Doc-SIG] Python docs in reST
Ian Bicking
ianb at colorstudy.com
Wed May 18 23:52:18 CEST 2005
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
More information about the Doc-SIG
mailing list