Documentation is not generated issuing 'make doc'

[Jari Häkkinen]

This is true on my Mac running OS X 10.5.2 and I am working against the 0.4 branch, i.e. not using the distribution package.

[Jari Häkkinen]

Hm, I found the reason for this issue. Doxygen was not installed on my machine.

Many changes were made to configure.ac for 0.4. One of the changes was to remove diagnostics for missing tools (except in debug-mode). I am not sure if this was wise. If you are in debug-mode, you are probably a developer. Do you then really need output about missing tools more than installers?

If we do not want diagnostics during ./configure maybe a make doc should say something about missing tools regardless debug modes and other conditions?

[Peter]

Hm, make doc could gave a message when doxygen is not available, but for other target ssuch as html, pdf, ps, or dvi, I think we shoule leave. Therefore, it would perhaps be useful to have some diagnostics in configure as well.

I mean I would recommend installers to check out from stable branch and build from there. That use case is ignored in current configure.

Simple solution would be to have diagnostics regardless if --enable-debug switch is given. Another solution would be to differentiate building from a dist and from a svn wc (see e.g. svndigest). A third solution would be to mute diagnostics when docs files are already available (which they are in a dist).

[Jari Häkkinen]

Replying to peter:

Hm, make doc could gave a message when doxygen is not available, but for other target ssuch as html, pdf, ps, or dvi, I think we shoule leave. Therefore, it would perhaps be useful to have some diagnostics in configure as well.

There is no reason to do html, ... if no doxygen is available. Doxygen is a requirement to generate any API docs.

I mean I would recommend installers to check out from stable branch and build from there. That use case is ignored in current configure.

How? You are still working with a WC, and I have the stable branch checked out.

Simple solution would be to have diagnostics regardless if --enable-debug switch is given. Another solution would be to differentiate building from a dist and from a svn wc (see e.g. svndigest). A third solution would be to mute diagnostics when docs files are already available (which they are in a dist).

What was the argument to remove diagnostics? I forget.

[Peter]

Replying to jari:

Replying to peter:

Hm, make doc could gave a message when doxygen is not available, but for other target ssuch as html, pdf, ps, or dvi, I think we shoule leave. Therefore, it would perhaps be useful to have some diagnostics in configure as well.

There is no reason to do html, ... if no doxygen is available. Doxygen is a requirement to generate any API docs.

But you just did make doc with no doxygen available. Doxygen is a requirement to generate docs.

I mean I would recommend installers to check out from stable branch and build from there. That use case is ignored in current configure.

How? You are still working with a WC, and I have the stable branch checked out.

What I meant was that we kind of assume two cases in our configure. Either you are a developer, check out from svn repo, and configure with --enable-debug; or you are a user, unpacking a tarball, and configure without --enable-debug. My point was that this assumption is not accurate since we are missing the case when checking out from repo and run configure without --enable-debug.

Simple solution would be to have diagnostics regardless if --enable-debug switch is given. Another solution would be to differentiate building from a dist and from a svn wc (see e.g. svndigest). A third solution would be to mute diagnostics when docs files are already available (which they are in a dist).

What was the argument to remove diagnostics? I forget.

The argument was that if you are downloading a dist, the docs would already included and you dont need doxygen since the docs would already be there. However, just realize now that we decided, in the last moment, to not distribute generated docs. This makes it much simpler, the simple solution above is the only sensible solution. If you don't have doxygen, you cannot generate docs, and should be warned about this when configuring.

[Jari Häkkinen]

Replying to peter:

Hm, make doc could gave a message when doxygen is not available, but for other target ssuch as html, pdf, ps, or dvi, I think we shoule leave. Therefore, it would perhaps be useful to have some diagnostics in configure as well.

There is no reason to do html, ... if no doxygen is available. Doxygen is a requirement to generate any API docs.

But you just did make doc with no doxygen available. Doxygen is a requirement to generate docs.

Ok, we do not understand each other here. Did you mean make html? I never do that directly and did not connect to this use case. Also, I never descend to doc to issue make doc, I always do that in the top level. In the top level there is no support for make html and others, so there is no need to catch this case. Anyhow, this discussion is made unneeded due to below decisions.

I mean I would recommend installers to check out from stable branch and build from there. That use case is ignored in current configure.

How? You are still working with a WC, and I have the stable branch checked out.

What I meant was that we kind of assume two cases in our configure. Either you are a developer, check out from svn repo, and configure with --enable-debug; or you are a user, unpacking a tarball, and configure without --enable-debug. My point was that this assumption is not accurate since we are missing the case when checking out from repo and run configure without --enable-debug.

Ah, but I practically never use --enable-debug, so I do assume more then two use cases. Well, nevermind.

Simple solution would be to have diagnostics regardless if --enable-debug switch is given. Another solution would be to differentiate building from a dist and from a svn wc (see e.g. svndigest). A third solution would be to mute diagnostics when docs files are already available (which they are in a dist).

What was the argument to remove diagnostics? I forget.

The argument was that if you are downloading a dist, the docs would already included and you dont need doxygen since the docs would already be there. However, just realize now that we decided, in the last moment, to not distribute generated docs. This makes it much simpler, the simple solution above is the only sensible solution. If you don't have doxygen, you cannot generate docs, and should be warned about this when configuring.

This is simple to fix. Always complain if no doxygen exists.

[Peter]

Yepp, only remove the two lines with if and fi.

[Peter]

fixed in [1285]