Documentation

[mattgwwalker]

Hi,

I was trying to build the documentation (because I did not see it online, as indicated in README.md).

I encountered two issues. The first was a warning about @HAVE_DOT@ and the second is that nothing appeared in the documentation.

@HAVE_DOT@

When I run doxygen from the doc directory, I get this warning:

doc$ doxygen
warning: argument '@HAVE_DOT@' for option HAVE_DOT is not a valid boolean value
Using the default: NO!

This seems to be caused by the line (in Doxyfile.in)

HAVE_DOT               = @HAVE_DOT@

Is this line correct? Or did I misconfigure something? I'm using doxygen version 1.8.18.

From what I can see, it looks like the other instances of @variable@ in Doxyfile.in are replaced in the Makefile. @HAVE_DOT@ is not.

No Content

When I look at the documentation that is produced, it seems that nothing is documented. Here's what I see when I click on the 'Encoding Options' on the Main Page:

Is this what you would have expected? I see a similar issue with the OpusFile documentation on the opus-codec.org website, so perhaps there is a common configuration issue?

Cheers,

Matthew

[rillian]

If you run ./configure it should check whether you have the dot program installed and then set the correct value when generating Doxyfile from the Doxyfile.in template. If you copied Doxyfile.in manually, you'll need to perform the @variable@ substitutions manually.

If you run make -C doc the included Makefile doesn't substitute this variable, which is a bug.

As for the blank pages, I get that with doxygen 1.8.17 as well. I'm not sure what the problem is; probably some version skew between the Doxyfile and the tool release. :(

[rillian]

@xnorpx any idea what's wrong here?

[mattgwwalker]

Ah, thanks for that! I had assumed that configure wouldn't be necessary for the documentation.

So for the next person, to make the documentation:

./autogen.sh
./configure
make -C doc

The configure step requires the opus library.

Perhaps, in order to make it simpler for others to access, a pre-compiled version of the documentation could be placed on opus-codec.org?

So now the issue with @HAVE_DOT@ has been made to magically disappear. Thank you.

However, this still leaves me with empty documentation :o/

Matthew

[mattgwwalker]

If you run make -C doc the included Makefile doesn't substitute this variable, which is a bug.

Running ./configure has eliminated the issue with @HAVE_DOT@. I suspect that the magic must be coming from the root Makefile, where HAVE_DOT is now defined.

[xnorpx]

yeah doc might need to be updated similar as I did with Opus, but not so familiar with these extra libs.