Online docs: make index search available everywhere
For the Windows Help version of the docs, the left side box has 4 tabs: Contents, Index, Search, Favorites. I now mostly use the Index tab. That means that I can enter an indexed keyword, topic, or object name and jump from place to place in the docs. The left margin of the online docs only has a text search box equivalent to the Windows search tab (which I essentially never use). The index is only available on the front page, possibly not even visible without scrolling. Consequently, people, especially beginners, tend to use the text search box when they should be using the index. The result is often useless. The issue came up on python-list about a beginner entering 'print' and getting nothing useful. With the Windows doc, 'print' in the index search immediately brings up print (builtin function) (twice, I did not look into why). The same thing in the search lists 153 pages, with the builtin functions page at 75. Not too surprising, as it is a long page with only 3 occurrences of 'print'. Also not useful. So I think the online docs should also have an always available index search box in addition to the text search box (which should be properly labeled as such). 'Enter a module, class, for function name.' should be applied to index search, not text search. An alternative is for the one box to give both index search results and text search results, but doing the latter when one only wants the former is a waste of both server and reader resources. I presume this suggestion does not belong on bugs.python.org, so I hope one of the docs people reading pydev will do something with it. -- Terry Jan Reedy
On Thu, Sep 6, 2012 at 8:13 AM, Terry Reedy
I presume this suggestion does not belong on bugs.python.org, so I hope one of the docs people reading pydev will do something with it.
Why do you assume that? Docs infrastructure suggestions can go on the tracker under "enhancement", the same as improvements to the docs wording. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 9/5/2012 8:53 PM, Nick Coghlan wrote:
On Thu, Sep 6, 2012 at 8:13 AM, Terry Reedy
wrote: I presume this suggestion does not belong on bugs.python.org, so I hope one of the docs people reading pydev will do something with it.
Why do you assume that?
My understanding is that the tracker is for the cpython repository at hg.python.org and my impression is that web code is elsewhere.
Docs infrastructure suggestions can go on the tracker under "enhancement", the same as improvements to the docs wording.
http://bugs.python.org/issue15871 -- Terry Jan Reedy
On Thu, 06 Sep 2012 13:15:14 -0400, Terry Reedy
On 9/5/2012 8:53 PM, Nick Coghlan wrote:
On Thu, Sep 6, 2012 at 8:13 AM, Terry Reedy
wrote: I presume this suggestion does not belong on bugs.python.org, so I hope one of the docs people reading pydev will do something with it.
Why do you assume that?
My understanding is that the tracker is for the cpython repository at hg.python.org and my impression is that web code is elsewhere.
That is true. However, the appearance and functionality of the doc web pages is entirely controlled by Sphinx, and thus by the sources checked in to the code repository. --David
On Thu, Sep 6, 2012 at 10:26 AM, R. David Murray
On Thu, 06 Sep 2012 13:15:14 -0400, Terry Reedy
wrote: My understanding is that the tracker is for the cpython repository at hg.python.org and my impression is that web code is elsewhere.
That is true. However, the appearance and functionality of the doc web pages is entirely controlled by Sphinx, and thus by the sources checked in to the code repository.
This raises a related question. Where should we file issues for Python-controlled things that are outside the scope of the cpython repository (or the devguide) and that are not issues with the tracker (which has its own tracker -- the meta tracker). For example, where should we file an issue for hg.python.org if we suspect the issue is with how we've customized things rather than with Mercurial's hgweb itself. The main bugs tracker has a component for "Devguide" but not for other non-cpython repository things like hg.python.org. --Chris
On Sun, Sep 9, 2012 at 6:18 AM, Chris Jerdonek
This raises a related question. Where should we file issues for Python-controlled things that are outside the scope of the cpython repository (or the devguide) and that are not issues with the tracker (which has its own tracker -- the meta tracker).
For example, where should we file an issue for hg.python.org if we suspect the issue is with how we've customized things rather than with Mercurial's hgweb itself. The main bugs tracker has a component for "Devguide" but not for other non-cpython repository things like hg.python.org.
As far as I know, we don't have a general ticketing system for python.org infrastructure. That may change at some point in the future, but in the meantime I just email python-committers or python-dev if I notice something that appears broken with the development infrastructure, or pydotorg-www for the website in general. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Sep 8, 2012, at 8:16 PM, Nick Coghlan
On Sun, Sep 9, 2012 at 6:18 AM, Chris Jerdonek
wrote: This raises a related question. Where should we file issues for Python-controlled things that are outside the scope of the cpython repository (or the devguide) and that are not issues with the tracker (which has its own tracker -- the meta tracker).
For example, where should we file an issue for hg.python.org if we suspect the issue is with how we've customized things rather than with Mercurial's hgweb itself. The main bugs tracker has a component for "Devguide" but not for other non-cpython repository things like hg.python.org.
As far as I know, we don't have a general ticketing system for python.org infrastructure. That may change at some point in the future, but in the meantime I just email python-committers or python-dev if I notice something that appears broken with the development infrastructure, or pydotorg-www for the website in general.
In the absence of a tracker for "other" Python development issues, why not allow such issues to be filed with the main tracker in the meantime? Otherwise, there is no clear way to record or track progress made on those issues. In the meantime, I will post my issue to python-dev. --Chris Sent from my iPhone
participants (4)
-
Chris Jerdonek
-
Nick Coghlan
-
R. David Murray
-
Terry Reedy