Keep test.support docs out of the global docs index

[elibendersky]

BPO	12652
Nosy	@warsaw, @birkenfeld, @ncoghlan, @ezio-melotti, @merwok, @sandrotosi, @willingc
Files	devguide_test_support.1.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/birkenfeld'
closed_at = <Date 2015-04-14.10:53:12.484>
created_at = <Date 2011-07-29.07:45:24.776>
labels = ['type-bug', 'docs']
title = 'Keep test.support docs out of the global docs index'
updated_at = <Date 2015-04-14.13:53:31.884>
user = 'https://bugs.python.org/elibendersky'

bugs.python.org fields:

activity = <Date 2015-04-14.13:53:31.884>
actor = 'berker.peksag'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2015-04-14.10:53:12.484>
closer = 'willingc'
components = ['Devguide']
creation = <Date 2011-07-29.07:45:24.776>
creator = 'eli.bendersky'
dependencies = []
files = ['22790']
hgrepos = []
issue_num = 12652
keywords = ['patch']
message_count = 8.0
messages = ['141337', '141339', '141426', '141446', '141447', '141448', '141449', '240868']
nosy_count = 9.0
nosy_names = ['barry', 'georg.brandl', 'ncoghlan', 'ezio.melotti', 'eric.araujo', 'eli.bendersky', 'sandro.tosi', 'docs@python', 'willingc']
pr_nums = []
priority = 'low'
resolution = 'out of date'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue12652'
versions = []

[elibendersky]

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.

[warsaw]

As I just mentioned on python-dev (via Gmane), I'm uncomfortable with moving the documentation for test.support into the devguide.

[birkenfeld]

-1 from me as well.

[ncoghlan]

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?

[elibendersky]

Nick, fair enough, but I think it would be more appropriate (and useful) to close this issue as rejected and open a new one.

[birkenfeld]

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.

[elibendersky]

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.

[willingc]

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.