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@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