[warning] Unabridged API: unexpected kind 'page' (IGNORED)

[aprotyas]

What

Doxygen is producing page tags for markdown files that are part of the include list in my project's Doxyfile. Currently, exhale is throwing a warning that reads (!) Unabridged API: unexpected kind 'page' (IGNORED). This is not a huge problem, because lexerMapping is supported, but it would be nice to get over this warning - both to have stable CI on my project, and to have builtin support for markdown pages.

Why

It looks like exhale does not qualify page as an input kind, and hence the appropriate defaults are not used for this input kind. I think a simple fix would be to allow users to append to exhale.utils.AVAILABLE_KINDS through exhale_args, and/or add support for the page input kind, which would map to a doxygenpage output directive for breathe. For the former option, users can do their own "customSpecificationsMapping" thing, and for the latter option, since there is a 1-to-1 output directive mapping, support for pages could be formally introduced within graph.py.

---

@svenevs: I would be happy to contribute through the second suggestion if needed. I would need some guidance though because graph.py is ginormous and I couldn't really make of where such a patch has to go.

Also, thanks a lot for the thorough documentation throughout the project!

[2bndy5]

This is not a huge problem

I agree. In fact, this problem is initially why I decided not to use exhale (upon first try a couple years ago). But here I am again.

EDIT: Oops, I thought this read "This a huge problem". Seems my eyes are buggin out.

[svenevs]

Please see #114 (comment) if you want page support getting a valid test case would be really helpful, I don't use pages and got stuck learning how to use them. I just need a couple example docstrings, you can just put them in comments there provided you are on with them being included in the test code. I'm rebuilding my computer this weekend and will slowly start resuming work on this project, but this one is a big change

[2bndy5]

FYI, you don't need to use \page cmds. If there is a .md file in the INPUT path, then doxygen will create a page for each .md file found 💯 .

Nonetheless, I did skim read that PR, but didn't delve to deep into the changes. If you think its in working order, I'll try it out tomorrow.

[svenevs]

Ah interesting. Yeah it's mostly working minus a few edge cases, the input md thing is interesting -- thanks!

[aprotyas]

If there is a .md file in the INPUT path, then doxygen will create a page for each .md file found 💯 .

IIRC, I believe I requested this feature because the way things would work is - an rst file with a markdown code block would be generated, which is not really the markdown file itself if that makes sense, i.e. it would look awkward.

[2bndy5]

an rst file with a markdown code block would be generated, which is not really the markdown file itself if that makes sense, i.e. it would look awkward.

Sorry, I don't understand. The page that breathe translates into rst renders just as if I wrote it in rst (even though doxygen parsed it from MD). This is why I use MD files to take advantage of doxygen's MD parser. By using breathe's

.. doxygenpage:: md_filename
    :content-only:

I can also bypass the need to use recommonmark extension and still get auto-reference links for free from doxygen. Additionally, MD tables generate as expected which is a significant problem with recommonmark (that will never be fixed).

@aprotyas I used to hail from Hamburg, NY!