Description

StevenHsuYL

opened on Sep 28, 2022

Issue body actions

Documentation

This issue is made for translation work of documentation.

The issue is that if a blank line was absent after .. impl-detail::, the Sphinx would not build the paragraph after this line during HTML file generation for zh-tw translation.
I found this issue in three .rst files:

Doc/library/queue.rst
Doc/library/readline.rst
Doc/howto/isolating-extensions.rst

A blank line after .. impl-detail:: is suggested in those places for a complete building of corresponding translation pages.
Thanks!

Linked PRs

• gh-97607: Fix content parsing in the impl-detail reST directive #97652

Reacted by Ezio Melotti and W. H. Wang

Activity

1. StevenHsuYL

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Sep 28, 2022
2. StevenHsuYL

   changed the title [-]Lack of blank line after `.. impl-detail::`[/-] [+]Lack of a blank line after `.. impl-detail::`[/+] on Sep 28, 2022
3. CAM-Gerlach

   added a commit that references this issue on Sep 29, 2022

   Don't parse content as arg in the impl-detail directive

   This issue will close once commit 00e5bcc is merged into the 'main' branch.

   00e5bcc
4. CAM-Gerlach commented on Sep 29, 2022

   

   CAM-Gerlach

   on Sep 29, 2022

   Member

   More actions

   To make a long story short, after a lot of digging and investigation, I've uncovered, tested and implemented in #97652 a fix to the underlying bug here—the custom impl-detail directive is configured to consume text in the same paragraph (either with no or one line break after the directive start ::) as an optional argument, rather than just taking no arguments and simply treating it as first content paragraph by default, as the built-in Docutils/Sphinx directives that behave similarly (e.g. the various admonitions) do. This results in it missing the evidently key metadata (e.g. raw source, file and line number) in the parsed doctree nodes, that in turn breaks the translation code that requires this metadata.

   Implementing the latter ensures translations work correctly for all three cases (0, 1 or 2 line breaks before directive content) anywhere the directive is used, now and in the future, makes the behavior consistent with the builtin directives, and substantially simplifies the directive code and logic, while not modifying the non-translated HTML output. See #97652 for the fix.
5. ezio-melotti

   closed this as completedin #97652on Oct 2, 2022
6. miss-islington

   added a commit that references this issue on Oct 2, 2022

   pythongh-97607: Fix content parsing in the impl-detail reST directive (…

   8ca39d5
7. ezio-melotti

   added a commit that references this issue on Oct 2, 2022

   gh-97607: Fix content parsing in the impl-detail reST directive (#97652)

   e8165d4
8. miss-islington

   added 3 commits that reference this issue on Oct 2, 2022

   pythongh-97607: Fix content parsing in the impl-detail reST directive (…

   c7957dc

   gh-97607: Fix content parsing in the impl-detail reST directive (GH-9…

   5ee8344

   gh-97607: Fix content parsing in the impl-detail reST directive (GH-9…

   8c528ef
9. serhiy-storchaka

   added a commit that references this issue on Oct 2, 2022

   pythongh-97607: Fix content parsing in the impl-detail reST directive (…

   299dd41
10. carljm

    added a commit that references this issue on Oct 3, 2022

    Merge branch 'main' into dictwatch

    e83abac
11. pablogsal

    added a commit that references this issue on Oct 22, 2022

    gh-97607: Fix content parsing in the impl-detail reST directive (GH-9…

    eb5cdf6

Issue actions