Zephyr: doc: API references such as :c:func:`funcname` aren't creating links

[dbkinder]

In documentation, a reference such as :c:type:`struct lwm2m_ctx` or
:c:func:`lwm2m_rd_client_start()` is not generating a link to the expected
API documentation.

It appears that the doxygen/Sphinx/Breathe processing is putting functions, types, and enums into the "cpp" domain instead of the expected "c" domain, but is putting macros into the "c" domain.

We can configure Breathe to use the "c" domain for instead of the "cpp" domain, but this will require a scan and fix of all uses of ":cpp:funct:" (et. al.). Alternatively, we document that the "cpp" domain should be used.

[ulfalizer]

There's a good recipe for a recursive search/replace here.

Better to fix it than to work around it, IMO, even if it's a big patch.

[dbkinder]

A quick scan shows there are currently 187 uses of :c:func: and 356 of :cpp:func:. I too am inclined to fix the Breath config, verify the links are being created as expected, and change the existing :cpp: domain references to :c:.

[pfalcon]

We can configure Breathe to use the "c" domain for instead of the "cpp" domain

I always found that docs calling Zephyr API functions "C++ functions" to be confusing, just didn't raise it so far. +1 for fixing to use "c" domain. I wonder if we actually should just bet on the default domain and use syntax like :func:.

[dbkinder]

Looking into this further, configuring Breath to use the :c: domain has issues as discussed in https://github.com/michaeljones/breathe/issues/386. Apparently Breathe's support for the cpp domain is more complete than for the c domain. When I switched the Breathe to use c by default, many declarations disappeared in the index. The recommendation in that Breathe issue was to keep Breathe configured to use the :cpp: domain. I'm trying out some other options still ...

[dbkinder]

Use of the default role "any", would let us write API links as `functionname` instead of :cpp:func:`functionname` and Sphinx/Breathe will hunt for functionname in all available domains, including both "c" and "cpp". But, the downside is if functioname is not defined it will throw an error, where today it renders OK but silently doesn't create an API link (might not be such a bad thing though).

[pfalcon]

But, the downside is if functioname is not defined it will throw an error, where today it renders OK but silently doesn't create an API link (might not be such a bad thing though).

Yeah, and I believe it's more like a warning in nature, i.e. the message is printed, but the docs are still generated fully. At least, that's how we have in MicroPython, where there're some terms referenced, but describing them is yet on TODO ;-). Not sure how that may affect CI, but I guess that can be handled.

Also, based on experience, sooner or later there may be ambiguity between refs of different types, e.g. `foo` may be :func:`foo` vs :macro:`foo`. But if there's ambiguity, sphinx will also report it. So, good plan to use just `foo` syntax, it's much easier to remember to use, so hopefully will increase quality of cross-referencing.

[galak]

What's left to address to fix this issue?

[dbkinder]

I'd call it "fixed" now. We could go through every :c:func:`xxx` reference and change to simply `xxx`, but that's not necessary right now since most of the references are working today with the domain-specific syntax.

[pfalcon]

@dbkinder: While working on https://github.com/zephyrproject-rtos/zephyr/pull/14912, I see cases when neither `xxx` nor :c:func:`xxx` works. Mostly FYI, didn't try to investigate those in more detail to report more detail. And that's in turn complicated by a couple of screensfuls of warnings generated during "normal" doc build process (so any possible warnings from user changes are drowned in them). Any ideas of doing something about those warnings?

[dbkinder]

@pfalcon Alas, there are some "known warnings" because of known issues with doxygen/Sphinx/Breathe interactions (such as the "duplicate declaration" and "Unexpected identifier" warnings you're seeing). We have a filtering process added to scan through the reported warnings looking for "known warnings" that's reporting the "No new errors/warnings." at the end of the run. Previously, we only wrote out when there were any new known issues, making a clean report, but that was removed by the devops team that wanted to see all warnings even if they were all "known". I'll approach the "devops team" again to see if we can put it back to a quiet report if all the warnings are known.

If you can give me an example of where no link is created, I'll investigate further.

[pfalcon]

(such as the "duplicate declaration" and "Unexpected identifier" warnings you're seeing)

Well, I'm also seeing warnings of ambiguous paths (for :file: or something), which I imagine, could be fixed. (Let me know if you'd need more info on those.)

If you can give me an example of where no link is created, I'll investigate further.

Ok, those cases can be see even right now in https://docs.zephyrproject.org/latest/reference/networking/sockets.html .

• From start of doc, search for "zsock_socket". You'll see that it has formatting as an xref, but there's no actual link to https://docs.zephyrproject.org/latest/reference/networking/sockets.html#_CPPv312zsock_socketiii
• Similarly, zsock_close, tls_credential_add, possibly other there.