Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Lack of a blank line after .. impl-detail:: #97607

Closed
StevenHsuYL opened this issue Sep 28, 2022 · 1 comment · Fixed by #97652
Closed

Lack of a blank line after .. impl-detail:: #97607

StevenHsuYL opened this issue Sep 28, 2022 · 1 comment · Fixed by #97652
Labels
docs Documentation in the Doc dir

Comments

@StevenHsuYL
Copy link
Contributor

StevenHsuYL commented Sep 28, 2022 •
edited by arhadthedev
Loading

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
@StevenHsuYL StevenHsuYL added the docs Documentation in the Doc dir label Sep 28, 2022
@StevenHsuYL StevenHsuYL mentioned this issue Sep 28, 2022
Merged
@StevenHsuYL StevenHsuYL changed the title Lack of blank line after .. impl-detail:: Lack of a blank line after .. impl-detail:: Sep 28, 2022
@bedevere-bot bedevere-bot mentioned this issue Sep 29, 2022
Closed
CAM-Gerlach added a commit to CAM-Gerlach/cpython that referenced this issue Sep 29, 2022
@CAM-Gerlach
Don't parse content as arg in the impl-detail directive
00e5bcc 
This does not change the (untranslated) output,
but ensures that the doctree node metadata is correct.
which fixes pythongh-97607 with the text not being translated.
It also simplifies the code and logic
and makes it consistant with the docutils built-in directives.
@CAM-Gerlach CAM-Gerlach mentioned this issue Sep 29, 2022
Merged
@CAM-Gerlach
Copy link
Member

CAM-Gerlach commented Sep 29, 2022 •
edited
Loading

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.

@miss-islington miss-islington mentioned this issue Oct 2, 2022
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Oct 2, 2022
@CAM-Gerlach @miss-islington
pythongh-97607: Fix content parsing in the impl-detail reST directive (…
8ca39d5 
…pythonGH-97652)

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

This does not change the (untranslated) output,
but ensures that the doctree node metadata is correct.
which fixes pythongh-97607 with the text not being translated.
It also simplifies the code and logic
and makes it consistant with the docutils built-in directives.

* Remove unused branch from impl-detail directive handling no-content case

This is not used anywhere in the docs and lacks a clear use case,
and is more likely a mistake which is now flagged at build time.
This simplifies the logic from two code paths to one,
and makes the behavior consistant with similar built-in directives
(e.g. the various admonition types).

* Further simplify impl-detail reST directive code
(cherry picked from commit e8165d4)

Co-authored-by: C.A.M. Gerlach <[email protected]>
@miss-islington miss-islington mentioned this issue Oct 2, 2022
Merged
ezio-melotti pushed a commit that referenced this issue Oct 2, 2022
@CAM-Gerlach
gh-97607: Fix content parsing in the impl-detail reST directive (#97652)
e8165d4 
* Don't parse content as arg in the impl-detail directive

This does not change the (untranslated) output,
but ensures that the doctree node metadata is correct.
which fixes gh-97607 with the text not being translated.
It also simplifies the code and logic
and makes it consistant with the docutils built-in directives.

* Remove unused branch from impl-detail directive handling no-content case

This is not used anywhere in the docs and lacks a clear use case,
and is more likely a mistake which is now flagged at build time.
This simplifies the logic from two code paths to one,
and makes the behavior consistant with similar built-in directives
(e.g. the various admonition types).

* Further simplify impl-detail reST directive code
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Oct 2, 2022
@CAM-Gerlach @miss-islington
pythongh-97607: Fix content parsing in the impl-detail reST directive (…
c7957dc 
…pythonGH-97652)

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

This does not change the (untranslated) output,
but ensures that the doctree node metadata is correct.
which fixes pythongh-97607 with the text not being translated.
It also simplifies the code and logic
and makes it consistant with the docutils built-in directives.

* Remove unused branch from impl-detail directive handling no-content case

This is not used anywhere in the docs and lacks a clear use case,
and is more likely a mistake which is now flagged at build time.
This simplifies the logic from two code paths to one,
and makes the behavior consistant with similar built-in directives
(e.g. the various admonition types).

* Further simplify impl-detail reST directive code
(cherry picked from commit e8165d4)

Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington added a commit that referenced this issue Oct 2, 2022
@miss-islington @CAM-Gerlach
gh-97607: Fix content parsing in the impl-detail reST directive (GH-9…
5ee8344 
…7652)

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

This does not change the (untranslated) output,
but ensures that the doctree node metadata is correct.
which fixes gh-97607 with the text not being translated.
It also simplifies the code and logic
and makes it consistant with the docutils built-in directives.

* Remove unused branch from impl-detail directive handling no-content case

This is not used anywhere in the docs and lacks a clear use case,
and is more likely a mistake which is now flagged at build time.
This simplifies the logic from two code paths to one,
and makes the behavior consistant with similar built-in directives
(e.g. the various admonition types).

* Further simplify impl-detail reST directive code
(cherry picked from commit e8165d4)

Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington added a commit that referenced this issue Oct 2, 2022
@miss-islington @CAM-Gerlach
gh-97607: Fix content parsing in the impl-detail reST directive (GH-9…
8c528ef 
…7652)

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

This does not change the (untranslated) output,
but ensures that the doctree node metadata is correct.
which fixes gh-97607 with the text not being translated.
It also simplifies the code and logic
and makes it consistant with the docutils built-in directives.

* Remove unused branch from impl-detail directive handling no-content case

This is not used anywhere in the docs and lacks a clear use case,
and is more likely a mistake which is now flagged at build time.
This simplifies the logic from two code paths to one,
and makes the behavior consistant with similar built-in directives
(e.g. the various admonition types).

* Further simplify impl-detail reST directive code
(cherry picked from commit e8165d4)

Co-authored-by: C.A.M. Gerlach <[email protected]>
serhiy-storchaka pushed a commit to serhiy-storchaka/cpython that referenced this issue Oct 2, 2022
@CAM-Gerlach @serhiy-storchaka
pythongh-97607: Fix content parsing in the impl-detail reST directive (…
299dd41 
…python#97652)

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

This does not change the (untranslated) output,
but ensures that the doctree node metadata is correct.
which fixes pythongh-97607 with the text not being translated.
It also simplifies the code and logic
and makes it consistant with the docutils built-in directives.

* Remove unused branch from impl-detail directive handling no-content case

This is not used anywhere in the docs and lacks a clear use case,
and is more likely a mistake which is now flagged at build time.
This simplifies the logic from two code paths to one,
and makes the behavior consistant with similar built-in directives
(e.g. the various admonition types).

* Further simplify impl-detail reST directive code
carljm added a commit to carljm/cpython that referenced this issue Oct 3, 2022
@carljm
Merge branch 'main' into dictwatch
e83abac 
* main: (2069 commits)
  pythongh-96512: Move int_max_str_digits setting to PyConfig (python#96944)
  pythongh-94808: Coverage: Check picklablability of calliter (python#95923)
  pythongh-94808: Add test coverage for PyObject_HasAttrString (python#96627)
  pythongh-94732: Fix KeyboardInterrupt race in asyncio run_forever() (python#97765)
  Fix typos in `bltinmodule.c`. (pythonGH-97766)
  pythongh-94808: `_PyLineTable_StartsLine` was not used (pythonGH-96609)
  pythongh-97681: Remove Tools/demo/ directory (python#97682)
  Fix typo in unittest docs (python#97742)
  pythongh-97728: Argument Clinic: Fix uninitialized variable in the Py_UNICODE converter (pythonGH-97729)
  pythongh-95913: Fix PEP number in PEP 678 What's New ref label (python#97739)
  pythongh-95913: Copyedit/improve New Modules What's New section (python#97721)
  pythongh-97740: Fix bang in Sphinx C domain ref target syntax (python#97741)
  pythongh-96819: multiprocessing.resource_tracker: check if length of pipe write <= 512 (python#96890)
  pythongh-97706: multiprocessing tests: Delete unused variable `rand` (python#97707)
  pythonGH-85447: Clarify docs about awaiting future multiple times (python#97738)
  [docs] Update logging cookbook with recipe for using a logger like an output… (pythonGH-97730)
  pythongh-97607: Fix content parsing in the impl-detail reST directive (python#97652)
  pythongh-95975: Move except/*/finally ref labels to more precise locations (python#95976)
  pythongh-97591: In `Exception.__setstate__()` acquire strong references before calling `tp_hash` slot (python#97700)
  pythongh-95588: Drop the safety claim from `ast.literal_eval` docs. (python#95919)
  ...
pablogsal pushed a commit that referenced this issue Oct 22, 2022
@miss-islington @CAM-Gerlach @pablogsal
gh-97607: Fix content parsing in the impl-detail reST directive (GH-9…
eb5cdf6 
…7652)

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

This does not change the (untranslated) output,
but ensures that the doctree node metadata is correct.
which fixes gh-97607 with the text not being translated.
It also simplifies the code and logic
and makes it consistant with the docutils built-in directives.

* Remove unused branch from impl-detail directive handling no-content case

This is not used anywhere in the docs and lacks a clear use case,
and is more likely a mistake which is now flagged at build time.
This simplifies the logic from two code paths to one,
and makes the behavior consistant with similar built-in directives
(e.g. the various admonition types).

* Further simplify impl-detail reST directive code
(cherry picked from commit e8165d4)

Co-authored-by: C.A.M. Gerlach <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

gh-97607: Fix content parsing in the impl-detail reST directive CAM-Gerlach/cpython
2 participants
@CAM-Gerlach @StevenHsuYL