search

yongrenjie / sphinx-exec-directive

Sphinx extension to run Python code blocks and display the output.
https://yongrenjie.github.io/sphinx-exec-directive/
MIT License
3 stars 3 forks source link

Add/intertext option #9

Closed tikuma-lsuhsc closed 1 year ago

tikuma-lsuhsc commented 1 year ago

Here my quick take of the :intertext: option (see #8 ). The text accepts rst syntax.

I edited the readme.md accordingly but no image has been added for the output of the example.

I also added pytest to the repo to test the PR (somewhat) easily. It only make sure the test sphinx project builds successfully, though.

yongrenjie commented 1 year ago

First of all, thank you!

I've just made one change, to use self.state.document.settings instead of generating fresh settings. My main motive was to preserve backwards compatibility with older versions of Sphinx/docutils, since docutils.frontend.get_default_settings was only introduced recently, in 0.19.0. But (although I didn't investigate this further) I also suspect it might make a difference with some settings in conf.py.

Regarding Sphinx testing, I think it can be somewhat simplified: since we are only checking whether the pages build (and not checking for any Sphinx internals), we can probably get away with just running the sphinx-build executable and checking whether it exits successfully. This is what matplotlib does with their plot_directive anyway: https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/tests/test_sphinxext.py

I'm going to implement it that way for now, though if we ever need to come back to the sphinx.testing module I will look up your code. :)

As for the repl option which you suggested, I've been looking around and I sense a simple enough way of implementing it using the answer here: https://stackoverflow.com/a/25558325 I think it probably wouldn't be compatible with the context options, but I reckon that's fine. I'll look into it some time soon.

tikuma-lsuhsc commented 1 year ago

@yongrenjie - Cool. thanks for merging. Please spice it up in any way you like. I'm a total noob when it comes to sphinx extension dev. Your approach to testing sounds good to me. I just bumped into the pytest fixture when I was researching how to test my PR (doing so within the project folder).

Now, I've got myself in the deep end of this rabbit hole over the weekend and ended up spinning off the repl auto-exec directives as a completely separate project:

https://github.com/sphinx-contrib/repl

I got it to be fully functional, ready to be uploaded to pip. I did start out exploring possibilities for this feature to be a part of this extension though. But I came to the conclusion that there is minimal overlap in the functionality: sphinx-exec-directive is designed to run a code block per directive (with context option to extend it) while my idea for repl was to have a background REPL process per document. Anyway, if you are curious, take a look at the repl project. If you think there is a place within this project, please feel free to incorporate it.