Skip to content

Automate creation of idlelib/help.html from Doc/.../idle.html #69405

Open
Open
Automate creation of idlelib/help.html from Doc/.../idle.html#69405
Assignees
terryjreedyStanFromIreland
Labels
buildThe build process and cross-builddocsDocumentation in the Doc dirtopic-IDLE

Description

@terryjreedy
terryjreedy
opened on Sep 23, 2015
BPO 25218
Nosy @terryjreedy, @zware

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 2015-09-23.03:42:34.985>
labels = ['expert-IDLE', 'type-bug', '3.7', 'build']
title = 'Automate creation of idlelib/help.html from Doc/.../idle.html'
updated_at = <Date 2017-09-11.20:55:28.824>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2017-09-11.20:55:28.824>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = False
closed_date = None
closer = None
components = ['Build', 'IDLE']
creation = <Date 2015-09-23.03:42:34.985>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 25218
keywords = []
message_count = 2.0
messages = ['251402', '301902']
nosy_count = 2.0
nosy_names = ['terry.reedy', 'zach.ware']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue25218'
versions = ['Python 3.6', 'Python 3.7']

Linked PRs

Activity

  1. terryjreedy commented on Sep 23, 2015

    @terryjreedy
    terryjreedy
    on Sep 23, 2015
    MemberAuthor

    This continues bpo-16893, which replaced help.txt with help.html for the Idle doc display. It also replaced the display classes with new classes in help.py. I currently create help.html in a .bat file. With Doc as current directory, it uses
    ..\pcbuild\python_d.exe -c "from idlelib.help import copy_strip; copy_strip()"
    With a change to the help.py if __name__ block so that
    ..\pcbuild\python_d.exe -m idlelib.help copy_strip
    would work.

    This issue is first about revising Zack Ware's makefile patch, https://bugs.python.org/file36975/issue16893-v4.diff, which adds an 'idledoc' target. It is attached to bpo-16893. It needs 'copy' replaced by 'copy, strip, and rename'. The command above requires finding a compatible python.exe, and I do not know if that is a problem.

    In normal use, 'idledoc' should only be invoked for the earliest 3.x getting maintenance patches, and the result merged forward.

    If this is resolved, it would be nice if the new 'idledoc' target were built as apart of the release process, and any changes checked in. But the latter should currently still be done for all 3.x branches

  2. terryjreedy
    self-assigned this
    on Sep 23, 2015
  3. terryjreedy
    added
    type-bugAn unexpected behavior, bug, or error
    on Sep 23, 2015
  4. terryjreedy
    added
    buildThe build process and cross-build
    topic-IDLE
    on Jun 19, 2017

  5. terryjreedy commented on Sep 11, 2017

    @terryjreedy
    terryjreedy
    on Sep 11, 2017
    MemberAuthor

    Zach, I currently build idlelib/help.html by first building a complete doc set and then copying from Doc/.../idle.html, stripping trailing whitespace on the say. One problem is that the result has a lot of extraneous stuff aside from the doc text itself: the code for the header, sidebar, and footer. These are a nuisance when committing changes and for extracting just the text we want.

    I would prefer to create a clean .html from Doc/library/idle.rst that just has the code for the doc, without the extraneous matter. Do you know how? I looked in Doc/make.bat and it says it will not work on single files.

    EDIT: fixed in #129873.

  6. terryjreedy
    added
    3.7 (EOL)end of life
    on Sep 11, 2017
  7. ezio-melotti
    transferred this issue fromon Apr 10, 2022
  8. terryjreedy
    added this to IDLE Issueson Jul 23, 2022
  9. erlend-aasland
    added
    docsDocumentation in the Doc dir
    on Jul 27, 2022
  10. terryjreedy
    removed
    3.7 (EOL)end of life
    on Aug 6, 2024

  11. StanFromIreland commented on Feb 6, 2025

    @StanFromIreland
    StanFromIreland
    on Feb 6, 2025
    Member

    Sphinx can be run with an empty conf like so:

    html_theme = 'basic'
html_static_path = []
html_js_files = []
html_css_files = []
html_show_sourcelink = False
html_show_copyright = False
html_show_sphinx = False

    And then stripping everything that is not in <section id="idle"> returns the desired result.*

    Maybe an action could be added that runs when idle.html is modified? It would build, extract the file and then create the conf and then a simple bash script with a counter to clean up.

    Otherwise we have to manually update with each PR. (This should probably be done in the meantime as it has not been done for a while)

    *The only thing left is :source: but maybe we can just modify the docs to a link to clean that up?

  12. terryjreedy commented on Feb 7, 2025

    @terryjreedy
    terryjreedy
    on Feb 7, 2025
    MemberAuthor

    I now use a custom .bat file to run sphinx and copy-trim the result. This works as long as I am the only one editing idle.rst and remember to run the .bat file.

  13. encukou commented on Feb 7, 2025

    @encukou
    encukou
    on Feb 7, 2025
    Member

    FWIW, there is some tooling for help() topics in Doc/tools/extensions/pydoc_topics.py and release-tools.

  14. encukou
    removed
    type-bugAn unexpected behavior, bug, or error
    on Feb 7, 2025
  15. github-project-automation
    added this to docs issueson Feb 7, 2025
  16. github-project-automation
    moved this to Todo in docs issueson Feb 7, 2025

  17. StanFromIreland commented on Feb 11, 2025

    @StanFromIreland
    StanFromIreland
    on Feb 11, 2025
    Member

    Adding a workflow for when a PR modifies /Doc/Lib/idle.rst would be better than updating with releases in my opinion.

  18. terryjreedy commented on Jan 3, 2026

    @terryjreedy
    terryjreedy
    on Jan 3, 2026
    MemberAuthor

    @StanFromIreland In PR #132723 you tried and due to problems rejected idea of auto updating help.html if older that idle.rst. I want to consider your alternative of adding a check. I am not sure if it passing should be required. It might work better with Z. Ware's idea of adding 'idledoc' target to makefile. What do you think?

  19. StanFromIreland commented on Jan 4, 2026

    @StanFromIreland
    StanFromIreland
    on Jan 4, 2026
    Member

    Adding the makefile target would be good, we already have one for regeneration of pydoc-topics.

    We could add a check to the existing check generated files workflow. Making it optional is also possible.

    We could also consider adding it to the release process, like pydoc-topics.

  20. StanFromIreland
    self-assigned this
    on Jan 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

buildThe build process and cross-builddocsDocumentation in the Doc dirtopic-IDLE

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions