Docs for deploy generator and review of existing info

[danimtb]

Docs for PR conan-io/conan#4972
Issue conan-io/conan#4847

• Added section for generator class reference
• Removed duplicated info in how-to about generator packages
• Updated custom integration in the integration section

[jgsogo]

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

[jgsogo]

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.

[danimtb]

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

[jgsogo]

I still think we should put this out of the list (in a line or in a tip/note):

Suggested change

	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.

[danimtb]

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

[memsharded]

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

[danimtb]

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

[jgsogo]

Fix conflicts