-
Notifications
You must be signed in to change notification settings - Fork 2.1k
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.
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
Intermediate transform stage between read and write phases #12698
Comments
Add a placeholder node and then use a post-transform to replace the placeholder node with the list of things. See for example, https://github.com/AA-Turner/cpython/blob/docs/audit-event/Doc/tools/extensions/audit_events.py A |
Hey, thanks for the prompt reply ! That part is already what I am doing, but I don't think it helps regarding my issue. Following my exemple, if I go with placeholder and a PostTransform in the write phase, this is what I would typically have after the read phase: env:
A.doctree: empty, directives just updated the env
C.doctree:
Then, I would need to:
But the writing phase is not ordered, so if the writing of C happens after the writing of B, the environment does not contain target information and the references cannot be resolved. Sphinx allows:
But not:
I feel like my issue arises from the fact that the (I hope I am not too unclear, I find it not that easy to describe my issue...) |
Ah, I didn't realise the targets were to items in the list. Perhaps you could use A |
Naming and phase wise, I guess this event makes sense.
|
Update regarding the two issues:
|
Is your feature request related to a problem? Please describe.
Yes. I am writing a Sphinx extension and here is a simplified version of my issue:
The first step is typically done in parallel in the read phase, where I can fill the environment, either directly in directive's run, or using special nodes and Transform.
The third step is typically done in parallel in the write phase, where I can just look for a target document/id in my environment and replace the role node with a reference node, either using the
resolved
event, or aPostTransform
.But I can't find a way to implement the second step. The reading phase is too soon, because we can't have a list of things to display in B, until after A has been read. But writing phase is too late, because we would need to store the target id of things displayed in B before C is being written.
Describe the solution you'd like
I initially implemented step 2 and 3 as
PostTransforms
with increasing priority, as I thought that a higher priorityPostTransform
was going to run on all doctrees before lower prioritiesPostTransforms
are applied. Since the point is that the writing phase can be parallelized, I understand why this is not the case.The two ideas that come to mind are:
For the record, I also did try to define an event handler for
env-check-consistency
which is actually in the middle of the two phases. But the list of updated doctrees is not available, as it is a local variable of builder functions, and not a property of the builder. And if I try to create such a list myself and retrieve the doctree, there is no easy API to do so.BuildEnvironment
does define aget_doctree
method, but it does not include access to the read cache, and for some reason, my changes wouldn't persist to the writing phase anyway.Describe alternatives you've considered
Could not see an alternative, but maybe I am missing something in how Sphinx works... ?
The text was updated successfully, but these errors were encountered: