Conditional execution of needimport

[jumbo172]

I am using the needimport directive to import needs from needs.json. However, I would like this to be conditional, based on a variable in conf.py. Is it possible to disable needimport globally somehow?

I have a page called need_import.rst:

###########
Need import
###########

.. needimport:: ../../build/html/needs.json
    :filter: type == "requirement"

The only way I can prevent the needimport being executed is by adding need_import.rst to exclude_patterns in conf.py. This then generates the following:

WARNING: document isn't included in any toctree

Is there a better method to do this?

[danwos]

When you get this warning, it normally means that your file is still processed and the set exclude_patterns does not work for it.

However, such conditional content handling can be done with the help of Jinja.
Here is an article about it: https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/

There is also an implementation as an extension:
https://github.com/tardyp/sphinx-jinja or https://github.com/sphinx-extensions2/sphinx-jinja2

[ubmarco]

Keep in mind that the approach outlined by https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/ changes the file type of any affected file to be Jinja. This affects tools down the road that read the files as RST.
I'd advocate for https://github.com/sphinx-extensions2/sphinx-jinja2 so the files stay RST and Jinja is only explicitly used where needed.