Doxygen support

[Zaeb0s]

Suggestion to add a tool for handling doxygen.

Just a simple tool which takes a Doxyfile as input and appends include paths of dependencies to the INPUT field before calling doxygen to generate output.

[memsharded]

Hi @Zaeb0s

Could you please clarify what would be the purpose of the tool? At first I thought you were asking for a doxygen package, something that you wrapped doxygen and you could use it as a build_require in your projects, but I think you want something different. Could you write a code snippet, of how you see the interface of that tool? How would you use it in your recipes? Thanks!

[Zaeb0s]

Hello @memsharded

Sorry about the lack of information I will try to clarify.

I am currently using this crude implementation of the tool which I am talking about doxygen.zip.

And to use the tool I do the following inside conanfile.py (all other build related stuff striped away).

def build(self):
    self.doxy = doxygen.Doxygen(self)

def package_info(self):        
    self.doxy.add_include_paths()
    self.doxy.build()
    self.doxy.build_latex()

Currently building inside the package_info method because I want to generate doxygen on the packaged header files only.

The result is a HTML page and/or a PDF which contains information not only about the current package but also all its dependencies.

[memsharded]

Ok, thanks for the info.

The bad thing is that such will fail when you are not building the package, because the build() method will not be called, and self.doxy will be undefined.

Also, it has another bad side effect. The doxy.xxx commands will be called everytime the package is consumed by another project or package, even if the docs have been already built (and it is a slow thing!) I think you really need to restrict building the docs in the build(), or if any, do it in the last thing in the package() method, but not the package_info() method.

Another question is: How do you consume docs that are inside a package? Because typically package artifacts are consumed with generators (cmake, etc) in build systems automatically, but there is no direct interface for users to read those docs. That would also help understand the global use case.

So I guess that such utility is a wrapper around some doxygen commands (I have used it, in the past, but I don't recall much). In that case, it shouldn't be very difficult to implement, I will label it accordingly. Thanks!

[Zaeb0s]

Ah, yes thank you for pointing that out I did not think about that.

With that in mind it should probably instead be used like the following:

    options = {"doc": [True, False]}
    default_options = "doc=False"
    def package(self):
        # self.copy calls...
        if self.options.doc:
            doxy = doxygen.Doxygen(self)
            doxy.add_dependencies()
            doxy.build()
            doxy.build_latex()            

Currently documentation is only generated for the top-level package and stored in Artifactory, this way all builds are always ready for release.

[memsharded]

This is currently not planned as a built-in Conan feature.

The doxygen package in ConanCenter can be easily used in recipes as:

    def build_requirements(self):
        self.tool_requires("doxygen/1.9.4")

    def build(self):
       self.output.info("Doxygen Version:")
       self.run("doxygen --version")

However, I am moving this to the "docs" repo, I think it could make sense to document this as a useful integration