> >Alright, I think there's now a sufficiently wide consensus to move the > >documentation of Lib/test and Lib/test/support in particular to the > >devguide, which raises a question: > > I haven't been following this thread, so I caught up on Gmane. > > I'm somewhat uncomfortable with this decision. I understand why you want > to > do this, but I still think it might not be the right thing. > > For better or worse, test.support is part of the standard library, so > moving >
Why is it part of stdlib though? Isn't the stdlib something that's exposed to all Python programmers? How should an ordinary programmer (not a core dev) know some parts of stdlib are out of limits, if they are even documented and appear in the index - should he read the note at the top of the documentation page? Imagine a desperate programmer behind schedule who is looking for some particular functionality in stdlib and finds it in test.support - will he not use it and later complain we don't keep backwards-compatibility. Sure, he's at fault, but I think we can make such cases much rarer by making the distinction between user-exposed modules and core-dev-exposed modules more explicit. > its documentation elsewhere sets a bad precedent to me. Many times I work > on > Python while completely off-line. If I've had the foresight to build the > docs > before I go off-line, all the better, but even if not, I have the .rst > files > to consult. Now I'll have to remember to *also* grab the devguide so that > I > have the complete documentation of the stdlib. > > I think this is because you're experienced and probably know all the contents of the devguide anyway. Junior core-devs need the devguide handy for other reasons as well. > I also think this underestimates how blurry the line is between users and > developers. Think about yourself: when did you suddenly graduate from user > of > Python to developer of Python? I know that I often talk to people who > would > consider themselves "just" users of Python, but feel comfortable with their > occasional spelunking into the Python tree looking for whatever nugget of > code > or documentation will help them understand their problem. > Isn't this what we're trying to prevent, though? One should never even have to look at test.support unless he's working *on Python*. > > The devguide, as useful and cool as it is, is still immature and hard to > discover. I think more time will improve its organization, and it's not > even > linked to from docs.python.org. > > Maybe this is the main point here - what makes it immature? What makes it hard to discover? Maybe these issues can be fixed. > So I'm curious, why is this move better than adding noindexes, or just > trusting users to understand the difference between test.support.unlink() > and > os.unlink()? If I currently search for 'unlink', os.unlink comes up first, > which is good, and that should be preserved. The presence or not of some > test.support.unlink documentation isn't going to make the search results > that > much better or worse (there's already 14 hits). > I think the unlink&rmtree functions are just a symptom. The real issue here is - what is the devguide for, and how is it different from Python's existing documentation? What should go into the official docs, and what should go into the devguide? Once we agree on these question, I think the test.support dilemma will solve itself. Eli
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
