Documentation fails to build corrrectly

[mouse07410]

Describe the bug

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:17: error: unable to resolve reference to 'linuxmacos' for \ref command
Running plantuml with JAVA...
type lookup cache used 152/65536 hits=476 misses=152
symbol lookup cache used 186/65536 hits=566 misses=186
finished...
Exiting...
FAILED: CMakeFiles/gen_docs /Users/ur20980/src/liboqs/build/CMakeFiles/gen_docs 
cd /Users/ur20980/src/liboqs && /Users/ur20980/src/liboqs/scripts/run_doxygen.sh /opt/local/bin/doxygen /Users/ur20980/src/liboqs/docs/.Doxyfile /Users/ur20980/src/liboqs/build
ninja: build stopped: subcommand failed.

To Reproduce
Clone and run the build.

Expected behavior
Successful generation of docs, of course.

Like

Generating XML output for page options-for-configuring-liboqs-builds
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/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 152/65536 hits=476 misses=152
symbol lookup cache used 186/65536 hits=566 misses=186
finished...

real	0m0.698s
user	0m0.159s
sys	0m0.108s

Built Doxygen documentation

Fix
Note: fix includes updating .Doxygen to conform to v1.9.8.

diff --git a/README.md b/README.md
index 7a51186fe..f9b49615d 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ liboqs is an open source C library for quantum-safe cryptographic algorithms.
                - [Limitations and Security](#limitations-and-security)
                        - [Platform limitations](#platform-limitations)
        - [Quickstart](#quickstart)
-               - [Linux/macOS](#linuxmacos)
+               - [Linux/macOS](#linux/macOS)
                - [Windows](#windows)
                - [Cross compilation](#cross-compilation)
        - [Documentation](#documentation)

and please do

$ cd docs
$ doxygen -u .Doxyfile

[baentsch]

Thanks for the report. Reproduced/confirmed. Couldn't confirm that using doxygen 1.9.8 fixes this with the patch above, though (tested on Linux x64).

Adding gen_docs as ninja test target in CI as part of fix would be prudent to avoid re-occurrence.

[mouse07410]

Couldn't confirm that using doxygen 1.9.8 fixes this with the patch above, though (tested on Linux x64).

The patch addresses the error described above, which was fatal for documentation.

Besides the patch, you need to update docs/.Doxyfile file via cd docs; doxygen -u .Doxyfile to take care of multiple warnings. Are you saying that you did that, and still are getting Doxygen warnings on obsolete/deprecated entries in .Doxyfile?

[baentsch]

Are you saying that you did that, and still are getting Doxygen warnings n obsolete/deprecated entries in .Doxyfile?

Yes and No: I did (all of) that but the error message is still

"error: unable to resolve reference to 'linuxmacos' for \ref command"

Need to dive a bit deeper into understanding how doxygen is (supposed to) work...

[mouse07410]

Even after my patch?! Are you sure the appropriate files are changed? Maybe it gets stale version from somewhere - because after my patch is applied there should be (there isn't) text linuxmacos anymore, anywhere in the file.

[baentsch]

Even after my patch?! Are you sure the appropriate files are changed? Maybe it gets stale version from somewhere - because after my patch is applied there should be (there isn't) text linuxmacos anymore, anywhere in the file.

Indeed -- there was a cmake cache. After cleaning it, everything works now. Thanks for providing a solution! But it seems doxygen 1.9.3 also works OK, even without the "Doxyfile" update: All it needs is the change to the link target ("linuxmacos"->"linux/macOS"). Do you want to do the PR or shall I do it?

[mouse07410]

I updated .Doxyfile to Doxygen 1.9.8 to get rid of the warnings. It didn't affect the docs, only the patch did.

And yes, please feel free to do the PR yourself. ;-)

[baentsch]

And yes, please feel free to do the PR yourself. ;-)

Thaaaanks.