`papyri.directives:only_handler`

source: /papyri/directives.py :441

Signature

   def     only_handler (    argument  :  str    ,    options  :  dict[str, str]    ,    content  :  str      )   →  list[Any]

Summary

Handler for .. only:: — always drop with a warning.

Extended Summary

.. only:: html blocks frequently contain .. raw:: html nodes, which must never reach the IR — raw HTML in untrusted doc sources is a security risk. We cannot safely parse Sphinx conditional expressions, so we drop every only block regardless of the condition.

TODO: this is the only HTML-adjacent handler and it should probably accept a passthrough=True option (or a set of safe condition expressions) so callers can opt in to receiving the parsed RST content when they know the block does not contain raw HTML. The handler would then parse content via parse() and return the resulting nodes just like other handlers do, rather than always returning []. Until that option exists, maintainers who want the content must rewrite or remove the .. only:: wrapper in their source.

Aliases

papyri.directives.only_handler