-
Notifications
You must be signed in to change notification settings - Fork 190
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
Error when parsing a directive option with ** #712
Comments
Heya, you just need to wrap the
Yes its a bit of a pain, but thats just how it works at the moment 😅 |
@chrisjsewell: True, I just found it out myself after thinking about the (YAML related) error message a bit. Then, I think a hint in the documentation should be added that even for the rst-equivalent field list syntax, ( /edit: wow your reply was super fast, thank you! |
I think @chrisjsewell we were talking a while back about changing these to not be YAML options, and follow RST a bit closer. I quite like that direction, especially with the block-attributes work that is going on, we are moving away from yaml (and its quirks) being the main way to parse the directive options. |
Yep exactly, really we want to be able to parse the option blocks without anything a complicated as YAML; which was the easiest thing to add initially but is annoying from an integration standpoint. I'd note:
For directive options, really all we need is a mapping of
is fine YAML does give you some additional nice features, for longer strings: # replace new lines with spaces
a: >
a really long
string
# keep new lines
b: |
a really long
string but the rest of the complexity is problematic The only place where we really need the full JSON capability currently is with |
One thing we have been considering is making the simple options simple:
and if you specify it as a YAML block, then it is parsed as YAML:
This I think gets you to have all of the usual things that mostly just work (strings, flags, numbers, booleans), and an escape hatch for doing very complex arguments without having to invent a new format. The second way of passing in metadata to a directive would be very opt-in, and only for those who really need it. |
Describe the bug
context
When parsing the following document snippet, I get an error:
I wrote a little sphinx plug-in to provide the "sw-package-import" directive. It takes an option
glob
("directives.unchanged") which takes a string, in this case the glob pattern "**", which should be passed directly to the directive.The following syntax also fails with the same error message:
When I replace the above snippet by this, it works:
When I put the string into double quotes in the examples 1 and 2, it also works:
expectation
I expected that the option strings are passed "as-is" to the sphinx/docutils directive parser, i.e. I expected all three styles to have the same result.
bug
Here's the error message I ran into with variant 1 and 2:
I interpreted the hint about YAML syntax right - if you put the ** in double quotes (which makes sure YAML interprets the argument as a string and not something else), the string "**" is returned as option value, as expected.
problem
This is a problem for us because we usually avoid using the extra "eval-rst" directive around sphinx directives to keep the documents shorter. It also feels kinda inconsistent. If this behavior is intended and as specified, I have missed the hint in the documentation. In this case, I kindly ask you to explain the argument parsing in myst markdown directives in more detail in the user documentation.
I think it's actually okay to put strings like these in double quotes, but the documentation should make clear that even the
:option: value
syntax differs from restructuredtext.Reproduce the bug
I did not publish the code of my little "sw-package-import" directive yet, but if you need that to get to the root cause of this error message, contact me directly.
List your environment
Python version: 3.8.10
OS: Ubuntu Linux 20.04
The text was updated successfully, but these errors were encountered: