-
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
Only Directive does not order text as expected #1488
Comments
From David Nichols on 2014-06-11 20:14:52+00:00 Created on XP SP3, Python 2.6. |
From Takayuki Shimizukawa on 2014-06-11 22:52:06+00:00 In short, it might a limitation of the All section definitions under the only directive make unexpected behavior. I think we should avoid to contain any section header in the |
From Takayuki Shimizukawa on 2014-06-11 22:54:41+00:00 Technically, doctree (intermediate data) keeps that node with wrong order. I think it's a limitation and is difficult to solve (not verified yet). |
From David Nichols on 2014-06-12 12:11:18+00:00 If the "test1 or test2" section contains only body text or a .. figure:: directive (which is how I initially found it), the order is still incorrect. The section is placed before the "test1" and/or "test2" sections. Not being able to use section header in an only directive is a deal breaker for me. |
From David Nichols on 2014-06-23 12:59:10+00:00 But isn't the doctree created by Sphinx? The node order is in fact wrong, which leads me to suspect Sphinx. The translators from doctree to whatever work correctly. The Only class in sphinx is defined in sphinx\directives\only.py, starting on line 324. The comment starting on line 340 states: "# Same as util.nested_parse_with_titles but try to handle nested sections which should be raised higher up the doctree." I haven't been able to figure out why the nested sections should be raised, or how it's done, but I suspect that the problem lies there. |
From Takayuki Shimizukawa on 2014-06-26 16:05:35+00:00 I'll try to describe what happen. First case.
As docutils definition,
(In fact, it's not true; docutils avoid unexpected section in any directive content.) If we try to apply a same structure to
It can be represented as:
However,
In this case, if Line 1419 in 4883e1e
Finally, we will get:
Next case.
Current only directive implementation translates it into:
Why How do you think? I think the spec is reasonable (but hard to understand). |
From Takayuki Shimizukawa on 2014-07-05 03:01:34+00:00
Please take a look that refs and let us know your opinion if you have a chance. |
From Deniz Bahadir on 2014-11-07 11:28:49+00:00 I did not understand what the blog-entry is talking about. (Probably, the automated translation is not very accurate.) However, I think the following test-case is even simpler to demonstrate the problem:
Is there really nothing which can be done to solve the problem? Then it sounds to me, as if Sphinx needs some kind of pre-processor (similar to the C/C++ pre-processor) which just removes inactive only-sections from the source-file before handing it over to sphinx-parser. |
From Takayuki Shimizukawa on 2014-11-08 07:34:43+00:00 I think there is no way to solve the problem with using current Speaking about your last case, I think it is possible to fix, but it seems hard. |
Learning reST to write user manuals. (Hardware products.) Devices can have one of three network connections so the format of one file is:
If the headings in the 'test1 or test2' section does not match the headings of 'test1' or 'test2' section, the 'test1 or test2' section appears before the 'test1' or 'test2' sections.
Attached are two ZIP files of the resulting html files. The test1, test2, and test3 tags are defined in the associated conf.py files.
The text was updated successfully, but these errors were encountered: