[docs] index directives for section text

Thu Aug 2 15:53:09 CEST 2012

I sent the e-mail below to this list a week ago but didn't get a
response. Are there any thoughts on it?
Here are a few more examples where I feel displaying the header at the
top might be a bit more useful.
http://docs.python.org/dev/reference/datamodel.html#index-36
http://docs.python.org/dev/reference/simple_stmts.html#index-23
http://docs.python.org/dev/reference/expressions.html#index-16
(For future reference, these links point to the sections on generator
functions, yield statements, and yield expressions, respectively.)
On Thu, Jul 26, 2012 at 1:44 AM, Chris Jerdonek
<chris.jerdonek at gmail.com> wrote:
> When marking section text for inclusion in the index, is there a
> preference for whether the index directive should occur immediately
> before or after the section header?
>> For example, "generator, function" in the index links here:
>> http://docs.python.org/dev/reference/datamodel.html#index-36
>> But the "Generator functions" header is not visible after clicking the
> link without scrolling (at least for me) because the directive appears
> after the header in reference/datamodel.rst:
>> Generator functions
> .. index::
> single: generator; function
> single: generator; iterator
>> This seems like common practice in some areas of the documentation,
> but it seems like the result might be less desirable.
>> Thanks,
> --Chris