Documentation about hooks

[markgalpin]

It may be too early in the process for this, but in artifactory plugins, we've given each plugin its own directory so that its test and readme functions can be clearly defined on an individual plugin-by-plugin basis. This allows us to test one plugin at a time etc.
Also this mandates an individual readme per plugin which tries to summarize what each plugin does, so a user can decide whether or not they want an individual plugin. Given how early we are in building plugins, that may be premature. On the other hand, having been responsible for the effort of creating those readmes a few years later in a repository without that documentation, it is definitely easier for everyone to do it up-front, so I figured I'd mention it now.

[jgsogo]

Hi! I think it is time to document the hooks, we are going to start using them and we must decide where to put the docs about each one.

Hooks (these are not plugins) should be little snippets adding a very small and concrete functionality at certain points of the Conan workflow, so they are not expected to have long docs, half page should be enough.

Personally I think that the best place could be the docstring of the module itself ([[1] or (https://github.com/conan-io/hooks/blob/master/hooks/bintray_update.py#L2)] [2]), this way we will be sure that the doc is distributed with the plugin, is accesible and automatic tools will be able to retrieve it.

Nevertheless, if we can gather that information automatically (in a Travis job, for example) we could think about collecting it and publish it: wiki pages, github pages, read the docs,.... what do you think? which one will be a good place for the users to access/find this documentation?

cc/ @danimtb @conan-io/community-leaders

[uilianries]

Hooks are not like plugins, it's one file script with simple helpers. I like docstring for this case, but I don't know if it's enough for some users.

Since we have some experience with readthedocs, we could use the same approach for hooks. Wiki and Github pages are great too, but I would keep all under same tool to avoid confusion. As conan-io/hooks are the "official" hooks, is there any change to insert in docs.conan.io?

[SSE4]

I am not sure docstrings are good choice, as they will require users to inspect python code, which implies some python knowledge. I already have heard many complains that conan requires python knowledge.
also, it makes documentation less discover-able, and it's not indexed by search engines (like Google, Bing, Yandex, etc), so it will be harder to find.

[jgsogo]

is there any change to insert in docs.conan.io?

🤔 it could be very interesting: conan-io/docs could clone this repo, gather the docs from conan-io/hooks and add them as a chapter/section in Conan docs...

[uilianries]

I am not sure docstrings are good choice, as they will require users to inspect python code

That's why I said "I don't know if it's enough for some users.". For many times I preferred read Conan code base directly instead to open the docs. But it's my way to work. But I agree with you, the documentation need to be friendly and with easy access, like readthedocs.

it could be very interesting: conan-io/docs could clone this repo, gather the docs from conan-io/hooks and add them as a chapter/section in Conan docs...

It would be great! I would prefer centralize all things in one address if possible, instead of creating a new documentation only for hooks or plugins. But real problem that I see is separate the information "what is hooks" in conan-io/docs and creating a new documentation address just explaining about each hook.

[jgsogo]

No, no, I mean: we can parse the hooks source code to get the docstring of each one (also rst format) and compile it inside the Conan docs. We get:

• docs are always close to the sources: docstring
• easy to read: it will be parsed and generated into a readthedocs (with links to the source code)
• in the same URL as the rest of the Conan docs

I think it is a win-win-win, although I don't know if we want to introduce this kind of dependency in the generation of Conan docs.

[uilianries]

It's a trade off in my opinion. Hooks is an Conan extension, so introduce it in conan-io/docs sounds a new dependency to be maintained, but on the other hand we will need to have a new documentation just for few hooks and the explanation about "what is a hook", "how to configure a hook" will be in conan-io/docs ... 🤔

Bincrafters has bincrafters.readthedocs.io, where we have package notes, for example, they are notes about how to use or maintain some specific packages. But who reads that? Only Bincrafters members I think. Eventually users send a message on Slack asking about, but they don't know about that documentation.

Since conan-io/docs is well known and centralized, it could be a good idea keep it together. The price will be less than explaining for many times the same thing about hooks on Slack or even on Github issues.

Where is @danimtb? he always has good ideas for documentation 😸

[danimtb]

I like the idea of having the documentation of hooks separated from conan itself. I know it is a different thing, but CPT docs are not included in the Conan documentation although it is a heavily coupled and heavily used tool. There is a section with a reference directly to the readme: https://docs.conan.io/en/latest/creating_packages/package_tools.html

So I would like to follow the same approach here https://docs.conan.io/en/latest/extending/hooks.html#official-hooks with a list of the "official" hooks and a link to the section of the readme in this repository.

Regarding documentation on the python files of hooks, I reckon a brief description on the top of the file it is something very useful

hooks/hooks/bintray_update.py

Line 2 in 5d35335

"""Bintray Package info update

and it could be the way to start the documentation in the general readme (we could create a python script to get this pasted automatically).

Another possibility would be to create folders for each hook and include a readme for it and get it linked in the main readme, but this could be done in the future.

[jgsogo]

I think that CPT is a completely different thing, CPT is not for end-users while all the docs and the hooks are made for them. I can use CPT or my own implementation (there are several examples out there), and we are not enforcing any of them for you own CI.

But related to hooks we do enforce users to use those from conan-io/hooks, to contribute with more functionality. There can be more hooks out there, but these are the officials ones and Conan itself relies on some common conventions: how to notify about missing requirements, how to handle configuration,...

I'm not saying that this documentation should be inside the Conan docs, I'm saying just that it is different and it should we thought in different terms.