From b2c391139b0a7ac28d8b35026338e0a4ad6f110f Mon Sep 17 00:00:00 2001 From: Daniel Woste Date: Fri, 29 Nov 2024 08:14:23 +0100 Subject: [PATCH] Esbonio workaround docs --- docs/extensions.rst | 40 ++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 41 insertions(+) create mode 100644 docs/extensions.rst diff --git a/docs/extensions.rst b/docs/extensions.rst new file mode 100644 index 000000000..972be5525 --- /dev/null +++ b/docs/extensions.rst @@ -0,0 +1,40 @@ +Further Extensions +================== + +Most Sphinx extensions are playing well with Sphinx-Needs, but some other are not. + +This pages provides some workarounds to get problematic extensions to work with Sphinx-Needs. + +Esbonio +------- + +`Esbonio `__ runs Sphinx for you automatically and provides +previews and language feature support in VS Code. + +However, it does some dirty hacks and keeps all Sphinx data alive between all the different Sphinx builds, +so that an extension must be desiged to be more or less stateless to work with this approach. + +This is not the case for Sphinx-Needs, and some flags need to be reset after a build to allow the next execution. +But this can be done by some extra lines of code in your ``conf.py`` file: + +.. code-block:: python + + def setup(app: Sphinx): + app.connect("env-before-read-docs", reset_sphinx_needs_for_esbonio) + checks.add_warnings(app) + + def reset_sphinx_needs_for_esbonio(_app: Sphinx, env, _documents): + """ See https://github.com/useblocks/sphinx-needs/issues/1350 """ + # sphinx-needs 2.1.0 + if hasattr(env, "needs_warnings_executed"): + env.needs_warnings_executed = False + + # sphinx-needs 4.1.0 + if hasattr(env, "_needs_warnings_executed"): + env._needs_warnings_executed = False + + # sphinx-needs 4.1.0 + if hasattr(env, "_needs_is_post_processed"): + env._needs_is_post_processed = False + +Based on the discussion in `GitHub issues 1350 `__ \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index e71c75452..e9541f000 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -209,6 +209,7 @@ Contents layout_styles api utils + extensions .. toctree:: :caption: Development