-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Have one clear API for calling Sphinx
without unintended side-effects (deprecate SphinxTestApp
?)
#12130
Labels
Comments
chrisjsewell
changed the title
Have a clear API for calling
Have one clear API for calling Mar 18, 2024
Sphinx
without side-effects (deprecate SphinxTestApp
?)Sphinx
without side-effects (deprecate SphinxTestApp
?)
chrisjsewell
changed the title
Have one clear API for calling
Have one clear API for calling Mar 18, 2024
Sphinx
without side-effects (deprecate SphinxTestApp
?)Sphinx
without unintended side-effects (deprecate SphinxTestApp
?)
I'll add something that I'm interested in: multiple calls to Use case: a high-performance reloading server that is very different to the |
In the context of testing, it'd also be nice if Sphinx exposed a pytest fixture for this. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Currenty, there is no clearly documented way to "properly" use Sphinx programatically.
By "properly", I mean in a way that could be called multiple times within the same Python interpretor, without any unexpected polluting of the global state, and thus act exactly the same as if each call had been made in a separate Python interpretor
At present, there are diverging ways to do this, for the main CLI and for test cases:
Its not really clear from first appearance, but these actually almost achieve the same thing:
docutils_namespace
, on exit, resets the directives/roles lookups and additional node visitorsSphinxTestApp.cleanup
resets the directives/roles lookups and additional node visitorsHowever, there are also clear differences:
patch_docutils
temporarily patches docutils in a number of ways, that do not appear to be addressed bySphinxTestApp
, in essence meaning you are not strictly testing the behaviour of Sphinx in production when usingSphinxTestApp
SphinxTestApp.cleanup
does addition global state cleaning, restoring:sys.path
,sphinx.locale.translators
, andsphinx.pycode.ModuleAnalyzer.cache
I feel this divergence is unecessary, and ideally there would be one clear way to call sphinx as an API, perhaps something like:
cc @picnixz and @jayaddison for discussion, as it relates to #12093 etc
An additional note (as I just mentioned in #12089 (comment))
is that it is not currently possible to temporarily turn-off colored logging output.
This is annoying for if you want to assert the content of the warning stream
In the CLI it can be turned off, but is then never reset to its previous state: https://github.com/chrisjsewell/sphinx/blob/fa290049515c38e68edda7e8c17be69b8793bb84/sphinx/cmd/build.py#L327
The text was updated successfully, but these errors were encountered: