Fix README.md to work with Doxygen release 1.10.0

[praveksharma]

Undoes changes from #1769 and re-introduces changes from #1715 to satisfy Doxygen release 1.10.0.

GitHub markdown provides a few extension in addition to the standard Markdown spec; a valid GitHub Markdown file isn't necessarily a valid Markdown file (see this comment by a Doxygen contributer). Changing #linuxmacos to either #linuxmacOS or #linux/macOS worked for me locally; I chose #linuxmacOS because that seems to keep the link intact at the moment.

CI containers currently use Doxygen 1.9.2, openquantumsafe/ci-containers#76 updates them to use Doxygen 1.10.0.

• Does this PR change the input/output behaviour of a cryptographic algorithm (i.e., does it change known answer test values)? (If so, a version bump will be required from x.y.z to x.(y+1).0.)
• Does this PR change the list of algorithms available -- either adding, removing, or renaming? Does this PR otherwise change an API? (If so, PRs in fully supported downstream projects dependent on these, i.e., oqs-provider will also need to be ready for review and merge by the time this is merged.)

[Martyrshot]

Looks good to me. :) Thanks for this

[SWilson4]

Thanks for taking care of this, @praveksharma!

[praveksharma]

@Martyrshot I forgot to mark the draft PR to ready for review, sorry about that. Merging is blocked till the changes get another approval.

[dstebila]

If we were to rename the section title from Linux/macOS to Linux and macOS would that result in a shortcode that is compatible with both Doxygen and Github?

[praveksharma]

If we were to rename the section title from Linux/macOS to Linux and macOS would that result in a shortcode that is compatible with both Doxygen and Github?

I considered that. Since both #linuxmacOS and #linux/macOS (I didn't state this explicitly but #linux/macos does not work) I think the issue is the upper case letters in macOS and not the /.

[dstebila]

If we were to rename the section title from Linux/macOS to Linux and macOS would that result in a shortcode that is compatible with both Doxygen and Github?

I considered that. Since both #linuxmacOS and #linux/macOS (I didn't state this explicitly but #linux/macos does not work) I think the issue is the upper case letters in macOS and not the /.

Okay... would Linux/Mac or Linux and Mac work?

[praveksharma]

Okay... would Linux/Mac or Linux and Mac work?

Either would work, I ended up going with Linux and Mac since that seems to better follow GitHub Markdown conventions (I could be wrong but I don't think the GitHub Markdown spec or the GitHub markdown formatting documentation explicitly address how section links handle non-alphabetic characters and uppercase alphabets).

[praveksharma]

I pushed some more changes: the CI needed to be tweaked a little once the CI containers started using the updated images from openquantumsafe/ci-containers#76. CI now uses scripts/run_doxygen.sh (which does some formatting to make GitHub markdown work with Doxygen) instead of calling Doxygen directly. I'm not why the older way earlier but doesn't anymore; for what it's worth, the new way of using scripts/run_doxygen.sh follows how ninja gen_docs generates documentation.

[Martyrshot]

Seems good to me, but I would wait for @SWilson4 @dstebila, and @baentsch to take a look. :)

[dstebila]

This comment seems to suggest a new feature controlling how anchors for headers are generated for Markdown files. Would this have solved our problem?

[praveksharma]

I think it might. I'll merge this so PRs with red CI can rebase to main and create a new PR to address configuring Doxygen more appropriately if that is applicable.