Explicit the ConanFile python class

[liberforce]

Right now the ConanFile class is pretty much a second-class citizen in the documentation. It's all for conanfile.py. The problem with this approach is that you end up with stuff like this: http://docs.conan.io/en/latest/reference/conanfile/methods.html#package

That's the documentation of the package method, yet it documents the copy method. It took me several minutes to be able to find that page. Even from the menu, even using your conventions of using parethesis after a method name, there is no reference to the copy method, only to conan copy or example calls of self.copy.

The grouping is also weird as the generators are out of the conanfile.py section, yet they may be used there. For me the conanfile.py documentation should just have links to the other sections of what can possibly be included in a conanfile.py. The documentation for the classes and methods of ConanFile should be really named ConanFile, and its methods and attributes should have a specific entry, even if they're only there for consumption and not to be overriden.

[danimtb]

ConanFile class should always be inside conanfile.py files. Most documentation references conanfile.py to differentiate it from conanfile.txt.

I think maybe we can say in the index of the conanfile section that it talks about the contents of the ConanFile class: https://github.com/conan-io/docs/blob/master/reference/conanfile.rst

BTW, copy method inside package() is not the same as in imports() and it is even not defined in other methods like source(). Moreover, the copy object is generated taking the conan commands into account to change current working dir or "output" dir. So it has to be documented inside those methods.

Regarding generators grouping, we think is better to have a separate section as they may require more explanations and the list will keep growing.

[liberforce]

ConanFile class should always be inside conanfile.py files.

Never said the opposite.

Most documentation references conanfile.py to differentiate it from conanfile.txt.

I didn't say conanfile.py should not appear. I just said that a python file has no methods, no attributes. Classes do.

BTW, copy method inside package() is not the same as in imports() and it is even not defined in other methods like source(). Moreover, the copy object is generated taking the conan commands into account to change current working dir or "output" dir. So it has to be documented inside those methods.

Then you're exposing implementation details to the user, and that's generally not a good thing to do. I'm looking for the copy method of the ConanFile class, and you tell me I should look at the package method of the conanfile.py section. That's bad discoverability. I can't even use the integrated search engine to find that information, as it returns garbage.

Don't think like a developer of the tool, think like a user of the tool. The user thinks "hey, how does that copy method works", not "hey, how does that copy method works in the context of a call to package because I know the implementation cares about the context".

Regarding generators grouping, we think is better to have a separate section as they may require more explanations and the list will keep growing.

Again, I never said the opposite. But the situation could really be improved to meet user expectations. I don't think I'm the only one to directly search a class or a specific class method. So what do you think about the following design:

• Keep the conanfile.py help page but just list sections with internal links to whatever can be used in conanfile.py. This means a link to a page dedicated to the ConanFile class, a link to the generators, the build helpers, and the tools.
• For the ConanFile class help, document all the available methods, and add hints about the call context. So a copy method section would have subsections corresponding to from where it is called. This will make discoverable the fact that the implementation is different according to the caller. Of course, the package method and others would feature an internal link to the right subsection in the rigth context. You could separate internal methods from consumer methods if you want.

This would allow to search for a copy method, and would IMHO be more friendly to developers used to read API documentation.

[rweickelt]

What @liberforce requested resonates pretty much with me. I find it extremely confusing that copy() does not have its own entry. If the behavior is different in multiple contexts, then explain it as part of copy's documentation and remove copy documentation fragments from other places.

Please also don't call it an object if it is used like a method.