The docs

[dstroy0]

Layout is ok, I'm open to change. I need to go through all the variables and really document them. Add code snippets, rename parameters for clarity if needed.

[dstroy0]

I generated some new icons. doxygen/doxygen#6783 causes Alt text in the html generated from README.md

[dstroy0]

testing autolinking on InputHandler.cpp->InputHandler.h UserInput members

[2bndy5]

FYI, Breathe doesn't make any effort to auto-link signatures to literal blocks of src code (doesn't use sphinx.ext.viewcode). There is no plan on adding that feature to breathe (it likely would break some theme compatibility if it did). You're pretty much limited to Doxygen for auto-linking signatures to src code. IMO, it isn't highly useful to have documentation that requires users to read the src code. Honestly, that would only best serve contributors for debugging purposes.

[2bndy5]

BTW, you don't need to manually add .. literalinclude:: directives for sphinx.ext.viewcode to work.

InputHandler/cli_gen_tool/docs/source/modules/cli_gen_tool.rst

Lines 8 to 13 in 491d796

	cli_gen_tool.py
	----------------
	.. literalinclude:: ../../../cli_gen_tool.py
	:caption: cli_gen_tool.py

The literal blocks of src code is auto-generated by the viewcode ext... The generated code-blocks just don't occupy valuable screen real estate (they are separate pages that are cross-referenced automatically).

As an example, I'll show you a link to my latest project's docs: https://circuitpython-homie.rtfd.io/en/latest/API/device.html#circuitpython_homie.HomieDevice. Notice the [source] links to a separate page that has back links to the API [docs].

[dstroy0]

That's really cool! I'm having fun playing with all the options after reading through the documentation for breathe. What I really want is to be able to click a link in the brief or desc and it jumps to the function in the source.

[2bndy5]

What I really want is to be able to click a link in the brief or desc and it jumps to the function in the source.

That feature doesn't exist for breathe.

[dstroy0]

I'm looking through doxygen and seeing if that's possible. If it's in the XML as a link in the details it should show up, right? Then I just need to search and jump to the text somehow. I found this: https://caniuse.com/url-scroll-to-text-fragment #:~:text=<text> and since the use case is for contributors and me I think that universal browser support isn't necessary as long as we note the feature coverage. What do you think?

[dstroy0]

and, as I envision it, the link is in the details and clicking on it jumps to the function in the raw source, highlights the function name text.

[2bndy5]

If it's in the XML as a link in the details it should show up, right?

I can tell you that the info required is output by Doxygen in the XML, but breathe doesn't do anything with it. In fact, the feature you're looking for is a long requested feature; I can't find the issue/thread anymore - they seem to have migrated the project to an org account named breathe-doc.

and, as I envision it, the link is in the details and clicking on it jumps to the function in the raw source, highlights the function name text.

The sphinx.ext.viewcode doesn't even do that. If you inspect the Doxygen HTML output, you'll find that is implemented with JS (using jquery 🤮 ).

[dstroy0]

Ok, I'm about to try something and I'll let you know in a few minutes if there's any fruit.

[dstroy0]

works in chrome by default:
https://github.com/dstroy0/InputHandler/blob/main/src/InputHandler.cpp#:~:text=readCommandFromBuffer(

works in firefox with this addon:
https://addons.mozilla.org/en-US/firefox/addon/auto-find-text-fragment/
I read through the source and didn't see anything weird or obfuscated.

[2bndy5]

Great that it works, but not great that readers would have to install an add-on in Firefox (I use Firefox).

[dstroy0]

Another downside is that the search is not case sensitive. But it works which is all that matters to me and I can customize the link text to class::method. in Doxygen https://doxygen.nl/manual/autolink.html so I think this is feasible. Pretty cool.

I put <a href="linkURL">link text</a> into the details and it jumps to the src.

For browsers that aren't enabled it still jumps to the source in git, fails through.

Working example:
https://dstroy0.github.io/InputHandler/lib/src/InputHandler_h_docs.html#_CPPv4N9UserInput15defaultFunctionEPFvP9UserInputE

[2bndy5]

I put <a href="linkURL">link text</a> into the details and it jumps to the src.

You can use MD notation for better readability in the doctring:

[link text](linkURL)

[dstroy0]

I'm going to try that right now, thanks! Great suggestion!

[dstroy0]

I couldn't figure out the syntax to make it work, or maybe I am missing a setting in the Doxyfile.

[dstroy0]

using the HTML tags works though so I'm going with that.

[2bndy5]

Doxygen supports standard MarkDown syntax out-of-the-box, and what I suggested is a standard markdown hyperlink (breathe can translate it from XML). Are you sure you typed it right? Quotes aren't required for the URL, and you can use inline markup within the link's text.

[`literal code` and regular text](https://github.com/dstroy0/InputHandler)

should render like so: literal code and regular text

[dstroy0]

I was typing it in exactly like that and it was not working before but it is now.

[dstroy0]

definitely was me not doing something right lmao

[dstroy0]

Now I'm trying to get doxygen to parse my hacky C. Time to take a break hahahahahaha

[dstroy0]

everything docs related is now in.... docs/