add note about arguments in shebang in modules (#1718)

* add note about arguments in shebang in modules

* update note about arguments in shebang in modules

* move notes about shebang in one warning

(cherry picked from commit 9076624)

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -32,7 +32,9 @@ Python shebang & UTF-8 coding
 
 Begin your Ansible module with ``#!/usr/bin/python`` - this "shebang" allows ``ansible_python_interpreter`` to work. Follow the shebang immediately with ``# -*- coding: utf-8 -*-`` to clarify that the file is UTF-8 encoded.
 
-.. note:: Using ``#!/usr/bin/env``, makes ``env`` the interpreter and bypasses ``ansible_<interpreter>_interpreter`` logic.
+.. warning::
+   - Using ``#!/usr/bin/env`` makes ``env`` the interpreter and bypasses ``ansible_<interpreter>_interpreter`` logic.
+   - Passing arguments to the interpreter in the shebang does not work (for example, ``#!/usr/bin/env python``) .
 .. note:: If you develop the module using a different scripting language, adjust the interpreter accordingly (``#!/usr/bin/<interpreter>``) so ``ansible_<interpreter>_interpreter`` can work for that specific language.
 .. note:: Binary modules do not require a shebang or an interpreter.
 

docs/docsite/rst/reference_appendices/faq.rst

@@ -182,7 +182,8 @@ Also, this works for ANY interpreter, for example ruby: ``ansible_ruby_interpret
 so you can use this for custom modules written in any scripting language and control the interpreter location.
 
 Keep in mind that if you put ``env`` in your module shebang line (``#!/usr/bin/env <other>``),
-this facility will be ignored so you will be at the mercy of the remote `$PATH`.
+this won't work and will be evaluated as one string (including the space between ``env`` and ``<other>`` space).
+Arguments are neither intended nor supported.
 
 .. _installation_faqs: