You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
From the pip3 install sphinx-execute-code, we must change the __init__.py
file so that it is python3-compliant.
.. code-block:: python
exec(code)
if sys.version[0] == 2:
from StringIO import StringIO
else:
from io import StringIO
output = StringIO()
err = StringIO()
Why is it necessary to change the approach followed initially in this extension?
The execute_code directive, as it is implemented in the pip3 package, is not suitable for
a lot of user cases.
Indeed, since exec is used for executing the code, it has the following limitations:
* Only `Python` code, compliant with the python version of `Sphinx`, can be used.
`Python3` codes can't be executed if `Sphinx` uses `Python2` and vice-versa.
* Only `Python` codes can be executed (because of the use of `exec`).
* In some cases, using twice the `execute_code` directive can lead to unexpected results.
For instance, if `execute_code` is called twice, and in each code snippet there is::
import logging
logging.basicConfig(level=logging.DEBUG)
the behviour is such that any log message of the first `execute_code` call is catched, but none
of the log messages of the second `execute_code` is catched. This is due to the `logging`
module of course. That behaviour come out of the code snippets being executed via `exec`.
See the :class:`codes.Example`.
Proposed approach
Use the subprocess package to execute the code snippets. Advantages of the approach:
* One can specify the code snippet `input language`, enabling `Python2` snippets to
be exectuted with `Sphinx` that uses `Python3`, and vice-versa.
* Other interpreted languages could easily be executed.
* Since each code snippet is executed in subprocesses, the problem with the `logging`
module does not occur anymore.
The only problem I see at the moment is that if the Python code is not correct,
it won't raise any error and Sphinx will not stop.
Attached files
Please find in the attachments all necessary files to build a simple Sphinx doc and
test the changes.
Hi,
I'm unable to import it due to an error in the init file, which i assume I what you've corrected above. I'm just getting starting with working with sphinx (and in general with installing packages, creating environments and the like)...are you able to provide some guidance on what I need to do to import the updated package you've attached here?
Welcome to ProposedPatch's documentation!
Preliminary remark
From the
pip3 install sphinx-execute-code
, we must change the__init__.py
file so that it is
python3
-compliant... code-block:: python
Why is it necessary to change the approach followed initially in this extension?
The
execute_code
directive, as it is implemented in the pip3 package, is not suitable fora lot of user cases.
Indeed, since
exec
is used for executing the code, it has the following limitations:Proposed approach
Use the
subprocess
package to execute the code snippets. Advantages of the approach:The only problem I see at the moment is that if the Python code is not correct,
it won't raise any error and
Sphinx
will not stop.Attached files
Please find in the attachments all necessary files to build a simple
Sphinx
doc andtest the changes.
Example documentation
.. automodule:: codes
Additional information
Version of Sphinx::
proposed_new_extension.zip
The text was updated successfully, but these errors were encountered: