[docs] [issue16893] Generate Idle help from Doc/library/idle.rst
Terry J. Reedy
report at bugs.python.org
Tue Sep 8 06:16:05 CEST 2015
Terry J. Reedy added the comment:
Trying to produce .txt from .rst or .html was the original idea but the result in the upload help.txt is not terribly good. We decided that it is reasonable these days to depend on a browser being present and use the webbrowser module to display the html in a browser. Some effort has been put into getting decent looking html from rst. On windows, the .chm installed with Python can be used as a backup should the browser not work.
The reason for not simply starting a browser on the online Idle page is that the online docs reflect the repository version of Idle, which may have features not in the released version. So a 'frozen' doc is needed. (Note that the .chm is already frozen.)
The steps and issues I see.
1. Should there be a separate idlehelp target, as in Zach's v4 patch, or should copying the one file be part of building the html files. The issue here is making sure that the idlelib/help.html is rebuilt at the time of release. Re-generating the html files is, I presume, part of the release process, whereas a separate step would have to somehow be added.
2. We already use webbrowser to start the online docs, I believe on all systems. The code can be reused with a different target.
3. Is an exact copy ok, or should some nagivation be removed? We need to try the file as is and see.
4. The html file should be added to .hgignore and not checked into the repository.
Python tracker <report at bugs.python.org>
More information about the docs