Fix 404 errors on C API reference

[dgmccart]

On the acquire-zarr C API reference, the following links open a 404 error page when clicked:

• struct ZarrStreamSettings
• "Go to source code of this file" for acquire.zarr.h
• "Go to source code of this file" for zarr.types.h

This error may result from other API links as well. We'd like to address the links that are known to cause errors and ensure no other links cause 404 errors.

[melissawm]

Hmmm I had solved those but somehow they came back. I'll take care of it

[melissawm]

Hi all - here’s an explanation of the issue:

• Doxygen only generates html and xml files, does not generate source .md files.
• Mkdoxy is a mkdocs plugin which generates .md files from doxygen sources.
• Both mkdoxy and doxygen generate separate files for acquire.zarr.h and zarr.types.h.
• Before, I was including the source .md files generated from mkdoxy into the c_api/index.md file, which made the entire API documentation fit into one page. The problem with this approach is that the internal links between files generated by mkdoxy/doxygen are not respected after the include, and they were broken.
• Because of the way mkdocs processes included markdown files, the entire folder/file structure of the c api documentation would be broken. Fixing the links manually after the pages were built would be cumbersome and probably not very sustainable, which would be contradicting the approach of autogenerating the API documentation. I was not seeing this problem before because of a detail in the local building process that was causing the files to resolve temporarily (but not when built from scratch).

My solution is to slightly change the configuration of the site and docs generation to have acquire.zarr.h and zarr.types.h documented in separate files as expected by doxygen/mkdoxy, and have an index page for the C API documentation. This fixes all broken links and keeps the documentation organized.

Please let me know if this is a reasonable solution. A preview of this solution is at https://melissawm.github.io/acquire-docs/dev/api_reference/c_api/

[dgmccart]

I like this option, but please add tiles on the index page to makes the docs more obvious. @aliddell could help with descriptions if you aren't comfortable taking a stab at those yourself. I am not familiar enough to recommend something.

[aliddell]

@melissawm This looks good to me

[melissawm]

I'll create the tiles and re-post the preview link in a PR. Thanks!