Autogenerate Code Documentation

[Lnk2past]

Maintaining documentation is always a chore, but nothing is more frustrating when the documentation itself is not up to date. I would be willing to work with Conan dev's to implement a system to automatically generate the documentation from the code. There are a number of standards and tools available to help facilitate this.

With sufficiently formatted docstrings and a consistent standard enforced during development, issues like the one I just wrote up, #695 , could be mitigated with little to no actual work.

[danimtb]

We consider our docs are well maintained but there is always room for improvement. We are willing to incorporate new tools that make our documentation better and the process to maintain it easier, so we are open for those new tools you mention!

However, I consider our docs should be focused on usage and how-to instead of documenting every single detail of our codebase.

[memsharded]

I think having automatically generated docs from the code is a good thing. Just a couple of observations:

• @danimtb it is a complementary thing, not a substitute for the current tutorial-style docs
• It won't be considered stable API. Having things documented in that docs won't be as binding as the main docs. Otherwise it would be impossible to provide compatibility.

[Lnk2past]

@danimtb The Conan documentation is great, and I absolutely agree that docs focused on usage are important, but the CMake page is just one instance of where the Conan reference does not match the Conan code, and I believe that this is a problem (deprecation or not). Check out tools.get() documentation. Other than in the provided example, there is no documentation of the destination parameter. This omission would also be mitigated by generating docs from the code.

@memsharded I am not sure I understand the second bullet, but I think I agree?

Ultimately, documenting the code separate from the code base begs for divergence. Keeping docstrings accurate still requires work, but at least as the code is being modified the documentation could be modified in the same PR.

As an aside, in the event where parameters are deprecated like in CMake.configure, Conan should warn the user about them upon usage. Otherwise, the recipe maintainer/user will not know that a breaking change is coming and that there is a better option. In my case, I was looking at a community recipe that is still using the old parameters, and until I looked into the Conan codebase I would not have known those param's were deprecated.