search

open-quantum-safe / liboqs

C library for prototyping and experimenting with quantum-resistant cryptography
https://openquantumsafe.org/
Other
1.89k stars 463 forks source link

Current "main" fails to gen_docs #1897

Closed mouse07410 closed 1 month ago

mouse07410 commented 2 months ago

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):

baentsch commented 2 months ago

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 commented 1 month ago

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

mouse07410 commented 1 month ago

I've created a potential fix in https://github.com/open-quantum-safe/liboqs/pull/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?