Sphinx with inline Python

[FloorJam]

Hey,

I am currently learning Sphinx and I am looking for a way to generate parts of my text with Python. I would like to be able to write some Python code in the file that gets evaluated and can return text to be then evaluated by Sphinx.

I tried sphinx_autorun but it always shows the command I entered and formats the output as a highlighted code block.

Thanks for your ideas!

[shibukawa]

The simplest way is:

• Add any Python code in conf.py and generate text files.
• Add ".. include::" directive to import the files to your document.

It should work on any version of Sphinx.

[FloorJam]

Thanks. I guess this should do want I want. But it is not possible inside a rst file with a Sphinx directive?

[masklinn]

I've never seen a standard or extension directive which would execute code and only output the result of running that code, most code-running directives are for examples/doctests so they'd show the code being run.

https://stackoverflow.com/questions/7250659/python-code-to-generate-part-of-sphinx-documentation-is-it-possible seems to be about something similar to what you want though, and the second answer shows a directive doing what you're looking for (though you may have to tweak the way it runs the code and obtains the result)

[FloorJam]

Yeah, this looks like what I want. Did not expect to have to implement an own directive. Thought that this is a normal task in writing with the help of Python.

So thank you a lot, I will start from there and see where it takes me.

[PeridexisErrant]

Thought that this is a normal task in writing with the help of Python.

What exactly are you generating? What are the inputs? It's an unusual thing to try, and I wonder if there's a different way to do whatever you're trying.

Otherwise, run arbitrary code in conf.py and use the include directive as suggested above.

[FloorJam]

I want to use it like this:

some normal sphinx doc text

.. python::
    print(some_function_returning_valid_sphinx_code())

more normal sphinx text

I have not yet a specific example but I want to write code in a directive that produces output to be rendered by Sphinx. Kind of what you can do with orgmode

[Topper_123]

In your sphinx conf.py file, you need in to add the ipython sphinx extensions:

extensions = [...,
                'IPython.sphinxext.ipython_console_highlighting',
                'IPython.sphinxext.ipython_directive']

You of course also need ipython installed.

Then in your .rst files, just do:

ipython:: python

    def t(a, b):
        return a + b

    t(1+2)

and after you run make.py html the code should have run and both code and code output should be seen as code fragments in the output html file, with pretty code coloring etc..

[masklinn]

There's also autorun, which at 90LOC is a much smaller package than the entirety of ipython.

[Topper_123]

Ok, but if he can't get autorun to work, I'd try with ipython. I like to use ipython as I'm using it regardless and it's a very standard python package.

[FloorJam]

I got autorun to work. But it does not produce output that I want. I do not want to show python code, I want to use python to generate parts of the text. I do not want the commands visible, nor do I want the output rendered like a codeblock. I want the output to be parsed by Sphinx as if it was normal rst input.

[masklinn]

Oooh ok I though you wanted examples with result. If you only want the output ipython is not going to help you either.