spacemanspiff2007 / sphinx-exec-code Goto Github PK

Prevent typo:
hide-output vs hide_output

print("●") works in python, but in sphinx, using

.. exec_code::

   print("●")

gives an ExtensionError:

ERROR:    print("●") <--
ERROR: 
ERROR: Traceback (most recent call last):
ERROR:   File "pfstate.rst", line 33
ERROR:   File "...\lib\encodings\cp1252.py", line 19, in encode
ERROR:     return codecs.charmap_encode(input,self.errors,encoding_table)[0]
ERROR: UnicodeEncodeError: 'charmap' codec can't encode character '\u25cf' in position 0: character maps to <undefined>

Extension error:
Could not execute code!

Let me know if there is more information I can provide.

It appears it's not the symbol in the source code, but rather the printing that is a problem, as this does work:

.. exec_code::

   print("●".replace("●", "circle"))

I understand that this plugin runs python code that is hard coded into the documentation. But in my use case I have example python files implementing my project that I would like run dynamically when building the documentation. Similar plugins have the option of doing something like the following:

.. exec-code::
   :filename: examples/hex_codes.py
   :linenos:

Do you think you could implement this for this project?
Thanks!

I need to set an environment variable before I include using exec_code. The following works just fine:

.. exec_code::
   :filename: /tmp/file.py

However, any code included before the :filename: directive causes errors:

.. exec_code::

   print('here')
   :filename: /tmp/file.py

ERROR: print('here')
ERROR: :filename: /tmp/file.py
ERROR:
ERROR:
ERROR:
ERROR: File "", line 3
ERROR: :filename: /tmp/file.py
ERROR: ^
ERROR: SyntaxError: invalid syntax

Extension error:
Could not execute code!
make: *** [html] Error 2

If I leave out the blank line, the :filename: include runs, but the print('here') line is ignored.

Is there anyway to execute some code before including a file?

I am running sphinx with the following command:

sphinx-build -nWT -b html -j auto docs build/docs/html

It looks like the j flag causes sphinx-exec-code to give the following warning:

Warning, treated as error:
the sphinx_exec_code extension does not declare if it is safe for parallel reading, assuming it isn't - please ask the extension author to check and make it explicit

For reference, I am running sphinx 4.4.0 and sphinx-exec-code 0.4

It seems that leading and trailing whitespace is removed when printing:

.. exec_code::

   x = "   bla   "
   print(x) # prints "bla", not "   bla   "
   print("\n" + x) # same here

This causes incorrect output when the initial spaces are required, e.g. when printing a pandas dataframe:

.. exec_code::
  
   import pandas as pd
   df = pd.DataFrame({"a": range(3), "b": range(6,9)}, pd.date_range('2024', periods=3, freq='MS'))
   print(repr(df))

the output is

a  b
2024-01-01  0  6
2024-02-01  1  7
2024-03-01  2  8

When all the code is hidden, for example:

.. exec_code::

   # --- hide: start ---
   print('Setup!')

then sphinx-exec-code 0.9 fails with:

Extension error:
Could not parse code markers at /path/to/index.rst:5 (exception: min() arg is an empty sequence)

The same instruction works with sphinx-exec-code 0.8.

Unicode strings are not supported by sphinx-exec-code in code output. The compilation of sphinx in pycharm raises a UnicodeEncodeError error and fails to execute.

Here is a minimalist example to reproduce the issue. In my code I extensively use unicode math symbols.

The rst file:

.. exec_code::

print('This is a beautiful unicode character: \u265E.')`

The console output of sphinx compilation:

Running Sphinx v7.1.2 checking bibtex cache... out of date parsing bibtex file C:\REDACTED.bib... parsed 8 entries building [mo]: targets for 0 po files that are out of date writing output... building [html]: targets for 34 source files that are out of date updating environment: [new config] 34 added, 0 changed, 0 removed ERROR: print('This is a beautiful unicode character: \u265E.') <-- ERROR: ERROR: Traceback (most recent call last): ERROR: File "test.rst", line 6 ERROR: File "C:\Users\REDACTED\AppData\Local\Programs\Python\Python311\Lib\encodings\cp1252.py", line 19, in encode ERROR: return codecs.charmap_encode(input,self.errors,encoding_table)[0] ERROR: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ERROR: UnicodeEncodeError: 'charmap' codec can't encode character '\u265e' in position 39: character maps to <undefined> Extension error: Could not execute code! Process finished with exit code 0

By the way, I love sphinx-exec-code, thank you for this excellent sphinx extension!