Question: How to provide needs_extra_links from within a sphinx extension?

[cpolzer]

Hello,

when working on sphinx extension to bundle my configuration for multiple sphinx-needs projects, how would one configure
the needs_extra_links = list(dict) or the needs_global_options?

The api gives us add_extra_option, which works well when bound to sphinx's "config-inited" phase, also adding need types via "add_need_type" is no problem.

I guess my question is, if there are examples available, for this? I checked the sphinx-modelling and some others, but was not able to find an example.

I am not sure, this is the correct channel to ask, please point to somewhere else if possible and needed...

Thanks up front and regards!

[danwos]

I'm not sure if I got your use case correct. So, let me try to rephrase it in my own words:
You want to create a new Sphinx-Extension, which cares about the configuration of other Sphinx-Extension? And the motivation is to share the same configuration between multiple projects?

If I'm correct, I have done something similar. But the configuration was provided by a versioned Python package and the project-specific conf.py imported this. Something like:

from my_conf import needs_types, needs_extra_options as my_common_options

needs_extra_options = ['my_projecT_configs'] + my_common_options

I'm not sure if it is a good idea to overwrite the config of an extension from another extension, as there are some many corner-cases, where config values may be changed at different events in the sphinx-build process.

[cpolzer]

Here is an example of such an extension.

I guess the problem is somehow connected to the sphinx phases we could use to "app.connect("phase", function_name())"?
I tried "config-inited" and "build-inited", setting the prio and so on. No luck on adding needs_extra_links

def setup(app: Sphinx) -> ExtensionMetadata:
    """Setup the sphinx extension."""

    # setting up extensions
    app.setup_extension("sphinx_needs")
    app.setup_extension("sphinx.ext.autodoc")
    app.setup_extension("sphinx.ext.viewcode")
    app.setup_extension("sphinx.ext.napoleon")
    app.setup_extension("sphinx.ext.intersphinx")
    app.setup_extension("sphinxcontrib.plantuml")
    app.setup_extension("sphinxcontrib.collections")
    app.setup_extension("myst_parser")
    app.setup_extension("sphinx.ext.extlinks")
    app.setup_extension("sphinxcontrib.test_reports")

    # adding dynamic functions
    add_dynamic_function(app, my_dynamic_function)

    # adding custom need attributes
    add_extra_option(app, "template_color")

    # add need type from extension
    add_need_type(app, directive="cheese", title="cheese", prefix="chee", color="#ffffff", style: str = "node")

    # provide templates# configure warnings
    app.config.suppress_warnings = suppress_warnings()
    app.config.show_warning_types = show_warning_types()
    app.config.needs_warnings = configure_warnings()

    app.config.needs_global_options = needs_global_options()

    # those extra links are not available at build time in the consuming project
    app.config.needs_extra_links = needs_extra_links()

    return {
        'version': '0.1',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

def configure_warnings() -> dict[str, str]:
    """bogus example, dont question the content..."""
    return {
        "spec_link_missing": "type == 'req' and len(links) == 0",
    }

def suppress_warnings() -> list[str]:
    return ["myst.xref_missing", "config.cache"]

def show_warning_types() -> bool:
    return True

def needs_global_options(enable_needs_edit_links: bool) -> dict[str, object]:
    """bogus example, dont question the content..."""

    return {
        "custom_needs_status_color": '[[my_dynamic_function("id")]]',
    }

def needs_extra_links() -> list[dict]:  # type: ignore[type-arg]
    return [
        {"option": "links", "incoming": "incoming_link", "outgoing": "links"},
    ]

[cpolzer]

p.s.: i would have never expected to work for a cheese factory.