Martin Blais wrote: > On 5/18/05, Ian Bicking <[EMAIL PROTECTED]> 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 / [EMAIL PROTECTED] / http://blog.ianbicking.org _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
