This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Keep test.support docs out of the global docs index
Type: behavior Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: barry, docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl, ncoghlan, sandro.tosi, willingc
Priority: low Keywords: patch

Created on 2011-07-29 07:45 by eli.bendersky, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
devguide_test_support.1.patch eli.bendersky, 2011-07-29 07:45
Messages (8)
msg141337 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-29 07:45
First step in transition:

Attaching a patch to devguide's runtests.rst to incorporate existing test.support documentation from 3.3 head, with some small markup changes suitable for the devguide.
msg141339 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2011-07-29 09:28
As I just mentioned on python-dev (via Gmane), I'm uncomfortable with moving the documentation for test.support into the devguide.
msg141426 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-07-30 07:04
-1 from me as well.
msg141446 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-07-30 16:13
Barry convinced me that the test.support docs need to stay in the same repo as the code they document, so -1 from me as well.

Changed issue title to reflect the real problem that inspired this suggestion (i.e. test.support.unlink et al appearing in the docs index alongside the actual functions they wrap).

Is there a :noindex: directive that will tell Sphinx not to index an entire section?
msg141447 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-30 17:11
Nick, fair enough, but I think it would be more appropriate (and useful) to close this issue as rejected and open a new one.
msg141448 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-07-30 17:16
Why is it more useful to open a new issue for the same problem?

Nick: there is no such option right now, but I can customize our Sphinx build so that test.support is ignored when building the index.  I'll do that if no better consensus is reached on python-dev soon.
msg141449 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-30 17:27
Georg, since the issue was originally opened to track the solution, not the problem, I just figured it may be useful to mention that this solution was rejected and close the issue, for better historical record. Otherwise some years from now no one will remember what the debate was and that the solution was overruled in favor of another.

It's just an opinion, though. I don't have strong feelings about this.
msg240868 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-04-14 10:53
Reviewed the issue history during the PyCon sprints. Thanks to all for the thoughts on this issue. I am closing this issue since any additional actions on this subject would be best filed as a new issue.
History
Date User Action Args
2022-04-11 14:57:20adminsetgithub: 56861
2015-04-14 13:53:31berker.peksagsetstage: patch review -> resolved
2015-04-14 10:53:12willingcsetstatus: open -> closed

nosy: + willingc
messages: + msg240868

resolution: out of date
2013-01-25 19:19:22brett.cannonsetnosy: - brett.cannon
2011-07-30 17:27:55eli.benderskysetmessages: + msg141449
2011-07-30 17:16:52georg.brandlsetassignee: georg.brandl
messages: + msg141448
2011-07-30 17:11:03eli.benderskysetmessages: + msg141447
2011-07-30 16:13:04ncoghlansetmessages: + msg141446
title: Move documentation of test.support into the devguide -> Keep test.support docs out of the global docs index
2011-07-30 07:04:29georg.brandlsetnosy: + georg.brandl
messages: + msg141426
2011-07-29 21:50:47sandro.tosisetnosy: + sandro.tosi
2011-07-29 12:14:27eric.araujosetnosy: + eric.araujo
2011-07-29 09:28:05barrysetnosy: + barry
messages: + msg141339
2011-07-29 07:52:37ezio.melottisetnosy: + ezio.melotti
2011-07-29 07:45:24eli.benderskycreate