Add a section in the docs about using Hy from Python.

[gilch]

This doesn't seem to be explained very well. My understanding is that you can

• import hy in a Python script and then import modules written in Hy. Naturally, Hy must have been installed for this to work.
• create a Python module foo with an __init__.py that does the import hy, and then just import foo. (Hy must still have been installed. I think.)
• compile with hyc and get a normal .pyc file. Import said .pyc. Does this still work? Do you have to install Hy too, or does the .pyc include that?

I didn't see any of this in the docs.

What if I want to eval (exec?) a string containing Hy code? Is there a way to do that from Python? Or can you only import? Can I launch a Hy repl from Python's? These capabilities are important for supporting doctest #1019. If these capabilities exist, they should be documented. If not, they should be added.

[gilch]

How to launch the Hy REPL from Python:

>>> import hy.cmdline
>>> hy.cmdline.run_repl()

[Kodiologist]

compile with hyc and get a normal .pyc file. Import said .pyc. Does this still work?

Yes, it does.

Do you have to install Hy too, or does the .pyc include that?

Usually, you will need Hy, because if you use any of a variety of Hy's builtins, an approriate import statement will be added to the top of the generated Python code.

[ghost]

What if I want to eval (exec?) a string containing Hy code? Is there a way to do that from Python? Or can you only import?

I don’t know if we can do this. If there is such a feature, it will be my pleasure to document it.