doc: Revert back to using breathe instead of docleaf

[kartben]

This reverts the subset of commits from #59570 that introduced docleaf and fixes #61284.

• Revert "doc: Switch to using docleaf for doxygen entities"
• Revert "doc: Update requirements-doc.txt to use docleaf"
• Revert "doc: Replace instances of 'Breathe' with 'Docleaf'"
• Revert "doc: Adjust docleaf configuration as needed"
• Revert "doc: Remove :members: on doxygengroup directives"

Also added a commit marking some apparently unsupported and recently added constructs in wifi.h (namely, arrays with designated initializers) as INTERNAL_HIDDEN as they seem to be causing an issue (and are AFAICT meant to be internal anyway).

CI-built doc website: https://builds.zephyrproject.io/zephyr/pr/61339/docs/

[carlescufi]

@michaeljones please provide your feedback here

[kartben]

@michaeljones please provide your feedback here

I think it's been provided in #61284 (comment) already

[michaeljones]

Yep, seems to be a necessary step given the license. Sorry that it wasn't clearer from the start.

If there is the interest and the funding behind Zephyr for such things then I'd be happy to discuss a license exception that could also apply to Zephyr derivatives. That said, it sounds like you have a path forward exploring a Doxygen focused solution.

[gmarull]

@michaeljones is breathe going to be actively maintained now that docleaf exists?

[michaeljones]

@gmarull - There are two partially active maintainers on Breathe. I won't be actively working on it (and honestly haven't meaningfully in a long time) but they might. Development is slow and primarily responds to changes in Sphinx to my knowledge. They would benefit from funding if that is an option.

[kartben]

Also added a commit marking some apparently unsupported and recently added constructs in wifi.h (namely, arrays with designated initializers) as INTERNAL_HIDDEN as they seem to be causing an issue (and are AFAICT meant to be internal anyway).

Mmm they're not that recent actually, so not sure why they are now failing (@gmarull @michaeljones any brilliant idea as to why this could be the case?). I guess I could add these as known warning but...
EDIT: they are not new, but only recently was the wifi_mgmt Doxygen group "mounted" in the Sphinx doc (#59859).

...
C:\Users\kartben\zephyrproject\zephyr\doc\_build\src\connectivity\networking\api\wifi.rst:30: WARNING: Invalid C declaration: Expected identifier in nested name. [error at 61]
  static const char *const wifi_twt_negotiation_type2str [] = {[WIFI_TWT_INDIVIDUAL] = "TWT individual negotiation",[WIFI_TWT_BROADCAST] = "TWT broadcast negotiation",[WIFI_TWT_WAKE_TBTT] = "TWT wake TBTT negotiation",}
...

Also, not sure they are meant to be internal either (although they might better off handled using helper functions just like other *_txt(...) helpers in this file? /cc @krish2718

Marking as DNM for now and will try to investigate more.

[gmarull]

actually... why do we have static arrays defined in headers? This should be in a C file...

[kartben]

+1, I actually raised the issue to @krish2718 in this discussion #60686 (comment)

[krish2718]

This originally was an inline function but was later changed to static arrays, I can move to wifi_shell.c and as extern (As they might be used by others).

[kartben]

If it's is desirable it can be used by others, and for consistency, would it make sense to turn it into a wifi_ps_txt() helper function, similar to how it's done for e.g.

zephyr/include/zephyr/net/wifi.h

Lines 52 to 75 in 4cbb9d8

	static inline const char *wifi_security_txt(enum wifi_security_type security)
	{
	switch (security) {
	case WIFI_SECURITY_TYPE_NONE:
	return "OPEN";
	case WIFI_SECURITY_TYPE_WEP:
	return "WEP";
	case WIFI_SECURITY_TYPE_WPA_PSK:
	return "WPA-PSK";
	case WIFI_SECURITY_TYPE_PSK:
	return "WPA2-PSK";
	case WIFI_SECURITY_TYPE_PSK_SHA256:
	return "WPA2-PSK-SHA256";
	case WIFI_SECURITY_TYPE_SAE:
	return "WPA3-SAE";
	case WIFI_SECURITY_TYPE_WAPI:
	return "WAPI";
	case WIFI_SECURITY_TYPE_EAP:
	return "EAP";
	case WIFI_SECURITY_TYPE_UNKNOWN:
	default:
	return "UNKNOWN";
	}
	}

Thanks!

[krish2718]

wifi_security_txt this was the original code, and wifi_ps_txt was also added but due to a review comment went with static array. So, will take care of converting this to static array and moving to C file.

[kartben]

So, will take care of converting this to static array and moving to C file.

Thanks! Please ping me when done so that I can update this PR accordingly.

[krish2718]

Sure, but lets not wait for that PR to be ready soon :), it might be a while.

[kartben]

FWIW I am waiting for #60686 to be merged so that the change from 195c01b can be taken care off there rather than in this PR.

[kartben]

@gmarull @jhedberg please revisit, I've now rebased to incorporate the latest changes in wifi.h that make breathe happy again.
CI built website: https://builds.zephyrproject.io/zephyr/pr/61339/docs/