Allow parsing needs options as multiline rst in custom layout

[fournier-p]

Hello,

When using the meta() function in the custom layouts, it's not possible to parse the needs options as rst, only the links are handled in a custom way and the rest is parsed only with inline rst syntax.

I have the need to be able to put multiline rst for some custom options and thought a dedicated meta_rst() function would be the best way to handle those.

I made this in an hour to see the feasibility of such a function so don't hesitate to tell me if there is anything that needs to be changed or improved. I also didn't touch the tests, I would need a bit a guidance to add/update tests for this feature.

Status:

• Implementation
• Documentation
• Tests

[chrisjsewell]

Heya @fournier-p thanks for the PR

I am a little hesitant about it, though, since it does not integrate well with the sphinx build system:
The layout creation here occurs in the "resolving" phase (see https://www.sphinx-doc.org/en/master/extdev/index.html#build-phases),
whereas, all parsing is already expected to happen in the "reading" phase.
Due to this, any parsing here will "miss out" on a lot of important transformations and post-processing.

For simple/local syntax, like making text bold/italic, ok this is not so much a problem.
But if there is any more complex syntax, like references, it will fail.

We already have issues with this for needextract, which attempts a similar thing, e.g. #890

[fournier-p]

Hey @chrisjsewell

Indeed the goal was mainly for local syntax, like lists for example. I also tried using some directives inside the option and it failed.

I don't know if this scope of local rst syntax is ok ?