Docs for deploy generator and review of existing info - #1262
Conversation
jgsogo
left a comment
There was a problem hiding this comment.
I would move the reference/generators/custom to mastering/custom_generator as it is not a reference about something that exists in Conan but something you can build on top of its functionalities.
Also, I would move the "Using template files for custom generators" section from howtos/custom_generators to mastering/custom_generator
| @@ -0,0 +1,91 @@ | |||
| .. _custom_generator: | |||
There was a problem hiding this comment.
I wouldn't add this to the list of available generators... I would put a comment below that list ("if none of these generators fits your needs, you can write a custom generator"):
linking to the howtos/custom_generators or integrations/other and merge all this content there, otherwise we will have three sections of the documentation talking about the same: how to write a custom generator, and it is too much from my POV.
There was a problem hiding this comment.
I understand what you mean, but we have different possibilities. The section at reference/generators/custom.rst is intended to be a reference of the generator class and the available attributes and properties. So I don't like the idea of moving it out of the reference but agree that making it part of the list is probably not ideal.
The integration part is a more generic one talking about the json generator, txt one, deps_cpp_info...
An finally the implementation of a generator package is covered in a how-to. All sections are properly cross-referenced and I think it makes
Co-Authored-By: danimtb <danimanzaneque@gmail.com>
| generators/premake | ||
| generators/make | ||
| generators/deploy | ||
| generators/custom No newline at end of file |
There was a problem hiding this comment.
I still think we should put this out of the list (in a line or in a tip/note):
| generators/custom | |
| If none of these generators fits your needs, you can create your own | |
| :ref:`custom generator <custom_generator>`. |
The only caveat is that we will need the :orphan: keyword inside reference/generators/custom.rst to avoid the rst error.
There was a problem hiding this comment.
Still don't like the idea of having the section so hidden, but I have taken your suggestion and we can change it in the future. Thanks for the helpful reviews
There was a problem hiding this comment.
I would also add an entry, linking to this, in Extending Conan. This is clearly a point of extension and should be summarized there. Can be a short summary: purpose, goal, brief description and short recipe and link to main page
There was a problem hiding this comment.
I think in that case we should move the how-to to the Extending Conan section. Otherwise, there would be too many entries for generators with bits of information around the place. I will create an issue apart so this PR can be merged
Docs for PR conan-io/conan#4972
Issue conan-io/conan#4847