Proposal: Better integration with Doxygen config files

[julianeisel]

WIP PR: #123 (contains more fixes, planning to split this up depending on outcomes here).

---

MkDoxy already supports passing doxygen configuration files (I'll call them Doxyfiles) via doxy-cfg-file but has some issues. I found these while trying to run MkDoxy with Blender's Doxyfile.

While it is useful to control the configuration via mkdocs.yml, more advanced setups will probably want to use Doxyfiles for configuration. This way projects can also keep using Doxygen independently of their MkDocs based documentation, e.g. to output their API documentation in different formats. Not much is needed to make this work well I think.

Issue: Doxyfile's "INPUT" ignored

The Doxyfile's "INPUT" configuration is completely ignored, and instead the src-dirs configuration of MkDoxy is used, which isn't clear or expected. This is a quite important setting, it's good to respect.

Possible solution

Not quite sure. Some options:

• The Doxyfile "INPUT" could be merged with src-dirs (make both absolute and de-duplicate - or does Doxygen ignore duplicates?)
• src-dirs is only taken if "INPUT" is empty
• Always use Doxyfile value. Empty "INPUT" is error.

Probably good to print out the resulting "INPUT" for the user.

Issue: Relative paths in Doxyfile don't work

Doxyfiles often use relative paths, e.g. to refer to the source code as INPUT or additional assets, like a footer.html. For this to work the Doxygen command needs to be executed from the directory these paths are relative to.

Possible solution

Always execute doxygen from the directory containing the Doxyfile? I think this is typically what projects expect, although we might have to provide a way to provide a different directory.

Issue: Fails because XML isn't generated

Our Doxyfile doesn't enable XML output, so running MkDoxy fails with little information: FileNotFoundError: [Errno 2] No such file or directory: '/tmp/mkdocs_qtqsplwy/assets/.doxy/Blender/xml/index.xml'

Possible solution

Since we run doxygen for the specific purpose of getting XML output, override the config so only XML output is generated.

Proposal on combining mkdocs.yml config with Doxyfile

I'd propose the following way to build the final configuration:

• Base configuration is doxy-cfg-file if provided, otherwise defaults as now
• Always apply format overrides: XML = YES, HTML = NO, LATEX = NO
• "INPUT" is src-dirs merged (de-duplicated) with Doxyfile's "INPUT"
• "OUTPUT_DIRECTORY" is always overridden with a temp directory, as now
• doxy-cfg entries always override (applied last, can override "INPUT" and "OUTPUT_DIRECTORY")

Unclear: Compatibility

The suggested changes would break compatibility. I'm not sure what the usual compatibility policy is in this project. It does seem to me however that the current doxygen configuration file support is too limited to be used, basic configuration files only work since #121.

[JakubAndrysek]

Hi, thank you very much for your help.

My previous configuration worked for my small project, especially without a real Doxyfile. But for I think it's time to make a change.
The proposal sounds promising, and I agree with your changes.

Compatibility

I don't know in which projects this tool is used, but this way of transformation will definitely help.
Half a year ago, I started the migration to the new Mkdocs schema, but because of my free time, I haven't finished it - Migration
But when we make more significant changes, it might also be possible to migrate validation process.

The new schema doesn't support dashes, so it will be necessary to change it to underscore.

Changes

If you have the time to update this project and add a better integration with Doxygen, I would be very grateful.

Thanks

[julianeisel]

Hey, thanks for the positive feedback!

Compatibility

So if I understand correctly you suggest doing my suggested changes together with switching to the new MkDocs config schema, and do one compatibility breaking release for both? Sounds good in general.

I've seen #110 before, it looks like a set of nice improvements! Is there much missing to get it finished? I guess issue is that such big changes are always hard to finish, esp for such a free time project. Maybe better to split it up an focus on the config schema changes first? I might be able to help a bit.

---

Just as as side-note, I'm currently just experimenting with MkDoxy to see if we can eventually use it for Blender. This isn't too high priority and really just an experiment. I'll try to contribute to address issues I find meanwhile, but it's possible that I'll have to drop out at some point. If we end up using MkDoxy for Blender we might be able to contribute some more.

[JakubAndrysek]

Hi, thank you for the explanation.

You got it right. The best way will be one braking release.

I think the schema has the highest priority.

Blender documentation

I appreciate that you are trying this plugin 😇

[julianeisel]

I think the schema has the highest priority.

👍 Is this something you're planning to get back at or do you need help?