Current "main" fails to gen_docs

[mouse07410]

Describe the bug

.  .  .
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/aes/
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/
Generate XML output for dir /Users/ur20980/src/liboqs/src/kem/
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/rand/
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/sha2/
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/sha3/
Generate XML output for dir /Users/ur20980/src/liboqs/src/sig/
Generate XML output for dir /Users/ur20980/src/liboqs/src/
Generating XML output for the main page
/Users/ur20980/src/liboqs/README.md:49: error: unable to resolve reference to 'oqs_algs_enabled' for \ref command
/Users/ur20980/src/liboqs/README.md:126: error: unable to resolve reference to 'build_shared_libs' for \ref command
Running plantuml with JAVA...
type lookup cache used 394/65536 hits=1015 misses=394
symbol lookup cache used 433/65536 hits=3672 misses=433
finished...
Exiting...
make[3]: *** [CMakeFiles/gen_docs] Error 1
make[2]: *** [CMakeFiles/gen_docs.dir/all] Error 2
make[1]: *** [CMakeFiles/gen_docs.dir/rule] Error 2
make: *** [gen_docs] Error 2

To Reproduce
Clone, configure with CMake, do make, then make gen_docs. Observe the above error.

Expected behavior
Successful generation of documentation. Speaking of which, it would be awfully nice to be able to output docs in PDF format.

Environment (please complete the following information):

• OS: MacOS Sonoma 14.6.1
• OpenSSL version 3.3.1 4 Jun 2024 (Library: OpenSSL 3.3.1 4 Jun 2024)
• Compiler version used: Apple clang version 15.0.0 (clang-1500.3.9.4)
• Build variables used: -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=/opt/local
• liboqs version: main branch

[baentsch]

Thanks for the report @mouse07410 . Unfortunately, I cannot reproduce this on the MacOS platform I have available (13.5.; clang-1500.0.40.1; doxygen 1.9.7). Which doxygen version are you using?

it would be awfully nice to be able to output docs in PDF format.

Sounds like a good idea. Do you have suggestions for tooling that could be used for that? At first glance, all that'd be needed is activating GENERATE_DOCBOOK & USE_PDFLATEX and using ghostscript, right? I don't have experience with doxygen so apologies for the possibly silly proposal. If you'd have that experience, feel free to do a PR.

[dstebila]

I can reproduce on my Mac running doxygen 1.12.0. I've created a potential fix in #1927, please try it out.

[mouse07410]

I've created a potential fix in #1927, please try it out

So far, very positive:

.  .  .
Generating XML output for page options-for-configuring-liboqs-builds
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/aes/
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/
Generate XML output for dir /Users/ur20980/src/liboqs/src/kem/
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/rand/
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/sha2/
Generate XML output for dir /Users/ur20980/src/liboqs/src/common/sha3/
Generate XML output for dir /Users/ur20980/src/liboqs/src/sig/
Generate XML output for dir /Users/ur20980/src/liboqs/src/
Generating XML output for the main page
Running plantuml with JAVA...
type lookup cache used 409/65536 hits=1015 misses=409
symbol lookup cache used 448/65536 hits=3672 misses=448
finished...

real	0m0.462s
user	0m0.209s
sys	0m0.193s

Built Doxygen documentation
.  .  .

it would be awfully nice to be able to output docs in PDF format.

Sounds like a good idea. Do you have suggestions for tooling that could be used for that?

Alas, I've pretty much zero experience with Doxygen too. :-(

At first glance, all that'd be needed is activating GENERATE_DOCBOOK & USE_PDFLATEX and using ghostscript, right?

it seems right, but I don't know. :-(

I don't have experience with doxygen so apologies for the possibly silly proposal. If you'd have that experience, feel free to do a PR.

Alas... But would you mind creating a PR with what you proposed above, and letting me to test it, like I did #1927?