Conan: [feature] custom information in Markdown generated files

[ericLemanissier]

Markdown generator is a great addition for usability, thanks! An improvement could be to allow recipes to define custom information, globally and per generator, so that recipes can document (for example) with which generator they can be consumed. This could be implemented with following attributes: self.cpp_info.doc = "markdown documentation" and self.cpp_info.docs["generator"] = "markdown documentation"

• [X] I've read the CONTRIBUTING guide.

[aleksa2808]

Regarding you specific example, shouldn't the point of packages be that they can be consumed with any generator? Personally I like the generators (markdown included) being as automatic and general as possible.

[memsharded]

An improvement could be to allow recipes to define custom information, globally and per generator, so that recipes can document (for example) with which generator they can be consumed.

Yes, exactly. It is a Conan goal that all packages should be able to be consumed by any build system that can be supported by a generator. We know that some private packages might be packaged with something very custom that makes them usable only with one build system. That is ok, as long as you manage that. But I think that Conan features shouldn't promote that.

I wouldn't mind if they provide more information, that could include the package description or even the docstring, but at the moment the generators do not have access to that information, and that will not be possible in the short term. Maybe after 2.0, generators will have more information available. But that is long term. At the moment, I am very excited about this UX improvement, thanks @jgsogo for bringing it!

[jgsogo]

If we want to walk that road I think it would be better to build on top of the graph.html file (not sure if a different command). From the CLI we have access to all the dependency graph and everything inside Conan, so we can show whatever we want from the recipes, make the graph more interactive with more information,... we can build on the fly a dynamic webpage 🙈

...but this is a _generator_ and we are limited to the information we have (and it is ok.... we keep working on it)

[ericLemanissier]

Another case where documentation per generator is needed is for recipes which cannot generate the same cmake targets/variables as upstream project, like https://github.com/conan-io/conan-center-index/issues/419
I don't mind where the information is made available to the user (graph.html vs markdown), but this information should probably be provided by recipes in self.cpp_info anyway.

[jgsogo]

We are working on the components feature that will make it possible to match any target name. Hopefully it will be ready for the next release. Once it is ready this generator has to list all the targets that are declared in the recipe.

About other variables, this generator can list everything declared in the cpp_info object. We can (and should) add the build_modules. We can list them and maybe include their content at the bottom of the file.

[ericLemanissier]

I may have another use case for this: changelogs. As @EugenMayer rightfully pointed this out in https://github.com/bincrafters/community/issues/1205#issuecomment-635128946

"public API changes".

• Be it that what changes in the dynamic-linking / static linking in glibc
• which flags are removed ( or added )
• what defaults have been changed
• What new dependencies have been added ( or removed )
• Which dependencies have been upgraded

[EugenMayer]

Just wanted to heavily encourage this work here! I really loved and also used https://github.com/bincrafters/conan-qt/blob/testing/5.15.0/CHANGELOG.md .. such a great value and tool to pick up the trace and what changed when builds fail.

Huge kudos!