IDLE: Update offline doc locations for linux

[RostyslavDzinko]

BPO	15808
Nosy	@terryjreedy, @ned-deily, @serwy
Files	issue15808_idle_doc_paths.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/terryjreedy'
closed_at = None
created_at = <Date 2012-08-29.11:23:43.793>
labels = ['expert-IDLE', 'type-feature', '3.10']
title = 'IDLE: Update offline doc locations for linux'
updated_at = <Date 2020-06-08.01:11:18.922>
user = 'https://bugs.python.org/RostyslavDzinko'

bugs.python.org fields:

activity = <Date 2020-06-08.01:11:18.922>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = False
closed_date = None
closer = None
components = ['IDLE']
creation = <Date 2012-08-29.11:23:43.793>
creator = 'Rostyslav.Dzinko'
dependencies = []
files = ['27052']
hgrepos = []
issue_num = 15808
keywords = ['patch']
message_count = 3.0
messages = ['169365', '169414', '169426']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'ned.deily', 'roger.serwy', 'Rostyslav.Dzinko']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15808'
versions = ['Python 3.10']

[RostyslavDzinko]

There's a possibility to add additional help sources in IDLE via

Options -> Configure IDLE... -> General -> Additional Help Sources

Use case:

If someone wants to download certain version of Python documentation in HTML and specify local "index.html" to be opened by custom menu item which appears the in Help menu.

Problem:

It's not possible to assign custom hot-key (Options -> Configure IDLE... -> Keys) for such menu items or reassign <F1> to that new menu-item, which actually makes sense when talking in context of the use case specified above.

This use case was taken from real life (stackoverflow site):

http://stackoverflow.com/questions/12174255/linking-offline-documentation-to-idle-linux

[ned-deily]

Actually, IDLE does have code to look for an on-disk copy of the html-formatted Python documentation set but the paths are platform-specific and, in the Linux case, are out-of-date for some distributions at least. For Linux platforms it looks for index.html in either /var/www/html/python or /usr/share/doc/python-docs-x.y/Doc/. On current Debian systems, for example, the Python doc package is installed in /usr/share/doc/pythonx.y-doc/html. If you install the doc packages and then create a link, IDLE should find the docs off-line when you select Python Docs from the Help manual. For example, for Python 3.3 you could do:

sudo aptitude install python3.3-doc
sudo mkdir -p /var/www/html/
sudo ln -s /usr/share/doc/python3.3-doc/html python

That said, the default locations should be updated. And perhaps a more useful customization would be to add a user configuration option for where to look for the on-disk copy of the docs rather than adding another hot key. (Also, older versions of Python are in security fix mode only.)

[ned-deily]

Here's a patch to update the doc paths to include current ones for Debian/Ubuntu and Fedora. The patch will have to be tweaked a bit for 3.2/2.7 to change sys.base_prefix to sys.prefix.

[terryjreedy]

Summer 2012 is about when I started doing non-trivial IDLE patches. Sorry I never really focused on this before.

On Windows, the chm file has been replaced by an html copy. #95841 patches the current code to use the registry to find the latter; it is possible that it already has a 'file:' prefix. I will merge this PR first. #95844 is about extracting this code into a module-level function.

I suspect that the 'new' linux/macOS locations might now be obsolete again. However, the bpo patch will be a start.

To make the code more robust, it could look in help sources for 'Offline Python Docs' and start the location list with anything it finds.

[simon816]

I suspect that the 'new' linux/macOS locations might now be obsolete again.

In recent versions of Ubuntu (22.04, 20.04, 18.04), the location is /usr/share/doc/pythonX.Y/html/

I think the best option is to have a configurable variable for search paths, which can be set by package maintainers to ensure consistency with their python docs package.

[terryjreedy]

System configuration variables are exposed in the sys module. I have no idea how things get there. But IDLE can at least look through known possibilities. The Ubuntu path is one that Ned proposed adding a decade ago, so paths may be fairly stable on each system even if diverse across them. And I can add an escape mechanism for user to add something.

[StanFromIreland]

Did you do this? The generated html could be updated a bit. At the top a link to the online docs and add inline links etc

[terryjreedy]

@StanFromIreland I know nothing about such Linux paths. An updated version of Ned's bpo patch would be great. If you use any non-trivial amount of his code, end the message section with an acknowledgement line.
Co-authored-by: Ned Deily <[[email protected]]>
Then request him to review.

[StanFromIreland]

@terryjreedy The current linux paths are mostly fine (/var/www/html/python/ -> rpm, /usr/share/doc/ -> dnf/apt) we do however have to check a few more directories as it can now be under python3 and not python-docs-3.

I will wait with this till the function is moved in #129971