Comments (9)
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
from hooks.
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
Line 2 in 5d35335
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.
from hooks.
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
from hooks.
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?
from hooks.
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.
from hooks.
is there any change to insert in docs.conan.io?
conan-io/docs
could clone this repo, gather the docs from conan-io/hooks
and add them as a chapter/section in Conan docs...
from hooks.
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.
from hooks.
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.
from hooks.
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.
from hooks.
Related Issues (20)
- [conan-center] Check exported patches are the same ones listed in conandata HOT 1
- [conan-center] Fragility on KB-H010: Can not detect new tools.get
- [conan-center] When test_package uses new CMake then test_v1_package must be present
- KB-H011 / KB-H022 test doesn't work correctly (false-positives) HOT 1
- [conan-center] KB-H0074: False positove when using self.info.clear() as optional
- shared library only exception for gobject-introspection
- Hooks does not like header_only=True and still looks for shared artifacts HOT 2
- Combinability with conan 2.0. HOT 5
- `pre_export(): could not get source code` on Windows
- How to remove cppstd from pure C projects? HOT 1
- conan-center hook KB-H075 has a false positive when giving example in comments about what consumer should do HOT 3
- Hooks sabotage conandata.yml generated in export method HOT 8
- Add a post_package_info hook to check that all libs listed in system_libs are lower case if host os is Windows HOT 5
- Add a post_package_info hook to check `cpp_info.resdirs`
- Add a post_package_info hook to check whether cpp_info.libs is empty if there is a shared option
- Question: Help on display of ccache stats HOT 10
- [conan-center] KB-H055: Wrongly detected on Conan v2 HOT 3
- hook activation in Conan 2.X HOT 2
- boost recipe now exceeds RECIPE FOLDER SIZE (KB-H009)
- [bug] header_only packages fail with no shared artifacts KB-H074
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from hooks.