docs
docs copied to clipboard
conan-io
Create cheatsheet for quick reference to Conan
I asked about this at a recent Conan online training - I would love to see something relatively succinct that gives examples of the most common Conan commands and arguments...
It was suggested to create a ticket - and I'm happy to have a go at starting a first draft, for others to shoot at...
Just recording some links here, for future reference...
I looked online for ideas for structure, and found this list:
https://github.com/detailyang/awesome-cheatsheet
Here's just one example, that's simple...
https://github.com/arslanbilal/git-cheat-sheet
Hi @claremacrae I think this is a great idea, something that would be very useful for Conan users and also would be useful to discover things that need to be improved in the Conan CLI for 2.0 version. Please, if you start the draft and want reviews on it or any help, don't hesitate to ask. Maybe we could throw some ideas in this issue.
Hi @czoido Thanks for your positive reply! It's very early days yet, but I started going through my Conan notes yesterday and started putting a file together...
https://github.com/claremacrae/docs/blob/cheatsheet/cheatsheet.rst
@czoido I would make much faster progress on this with someone to pair with - so if you'd be up for a little bit of screen-sharing and joint editing, that would make a huge difference!
Sadly I'm afraid I'm not using Conan enough for it to be feasible for me to make much progress on this.
If anyone else can work on it, I'm happy to review and give feedback...
@claremacrae I had a go at this - the results are here:
https://github.com/danpetry/docs/blob/cheatsheet/cheatsheet.rst
Are you happy for me to go ahead and raise a PR for it? Feedback would be very welcome.
Hello - and thanks for all the work you've done on this...!
I started writing up some thoughts but it got a bit long, and this is quite a low-bandwidth way to communicate...
I'm in UK time-zone, would you be willing chat online about it, and experiment together with a couple of edits to see what they look like?
My email address is in my GitHub profile...
@danpetry this is outstanding and really valuable cheatsheet. I'm really glad you created it and contributed it. I'm going to try to figure out what we can do to promote it. Thanks again @claremacrae for the great suggestion!
@solvingj I agree, @danpetry made an absolutely amazing start...
At the moment, the document is brilliant for those who already know Conan well, for example what each of these are: <package>/<revision>@<user>/<channel>. It's kind of a quick-reference, and is fantastic at doing that.
I was more thinking of a cheatsheet as being targeted more as for people who are not yet so familiar, partly to show what's possible and where to look for more info, and partly to show them the absolutely basics, by example.
To try to show what I mean by that, I just pushed some edits that I'd been playing with, on top of that work.
https://github.com/claremacrae/docs/commit/5f0d646dbcf2c13e56a39438ccf87b2c6886b8b9
I was thinking to try and show an example or two for each option.
@solvingj thanks! and thanks for teaching me Conan ;) This is basically a summary of what's in the tutorials.
@claremacrae ok, I had targeted it as a summary/reference for people who have already learnt Conan using some other method. To clarify and solidify the ideas, as well as reduce the need for memorizing common commands and going into the docs for commands and concepts that are very commonly used.
Hence, e.g., the detailed conanfile.py all in one place with lots of details on it. The idea there being that people can readily understand recipes that have already been written, and point them towards the important methods for what they're trying to do if they're writing their own. But I think this would be overwhelming for someone who is a complete beginner. Also, the direction of the titles is geared towards someone asking themselves: "how do I do xxxx, again?" They have some reminders in an intro of the important parts of the general concepts, but don't necessarily explain concepts from scratch, and then give some straightforward instructions on the commands that need to be used, including most useful arguments/flags.
Maybe it would be good to align on the purpose? IMO, things are generally better if they have one clear purpose, rather than trying to do multiple things, so I would propose that just one purpose would be best. Happy to discuss...
@solvingj it's not quite ready to go re raising a PR, but I will raise one in the coming weeks... sorry for the slow movement, there are some other things I need to sort out on my side before doing that.
As @claremacrae said, examples are really nice for cheat sheets. Probably always want them. Also, a LOT of people who would use cheat sheets would be novice users, so novice-targeting material really seems good.
However, as @danpetry said, what he's done is probably overwhelming for novice users.
IMO, seems like it could/should just be two separate cheat sheets: maybe like essentials/advanced. Also, with this kind of thing, I'd rather see you both just enjoy the freedom of creating it exactly how you want without worrying about conflicting priorities. If you both just make separate cheat sheets, one targeting essentials, one targeting advanced, we probably end up with two really great and complimentary documents.
Also, at some point, remember that all of this is redundant to documentation, and whatever you both choose to put on these types of cheat sheets is arbitrary and subjective. You don't want to try to re-create the documentation in a 1-page format. So, since you won't be able to fit it all, and there's an overwhelming amount of content to choose from, just choose "a bunch" of what you feel is important and don't agonize too much over the details.
Finally, also remember that Conan 2.0 is now being heavily developed, so start to think about labeling these as "Conan 1.x cheat sheets", and then maybe plan to have "Conan 2.x" variants later if you have time when that comes out (not any time soon btw, many months probably)
@danpetry Thanks a lot!
Also, a LOT of people who would use cheat sheets would be novice users, so novice-targeting material really seems good. IMO, seems like it could/should just be two separate cheat sheets: maybe like essentials/advanced.
I use cheatsheets all the time and mostly for stuff I already "master", especially CLI's as there is no consensus on how to do things, and remembering every switch, execution order, or gotchas becomes very hard once you use more than 10 tools daily.
I might be wrong but beginners should read the manual and not a cheat sheet...
@claremacrae and I had a conversation about this - we reckon that with a few additions it could cover some more of the basics in one sheet. Personally as a consumer of this sheet myself I feel like I would be switching back and forth between two sheets, as I still haven't memorized all of what could be considered "basics".
Anyway, sorry for the slow progress on this, I'm doing it in what time I can... anyone who wants to feel free to submit a PR against https://github.com/danpetry/docs/tree/cheatsheet. It still needs some homogenizing before submitting a PR to the actual conan docs repo, I think. Depending on opinions from the maintainers.
I use cheatsheets all the time and mostly for stuff I already "master", especially CLI's as there is no consensus on how to do things, and remembering every switch, execution order, or gotchas becomes very hard once you use more than 10 tools daily.
I'm glad to hear that.
I might be wrong but beginners should read the manual and not a cheat sheet...
The PDF of the Conan 1.35 manual runs to over 700 pages, and even starting to work your way around the conan docs is quite a daunting prospect.
When I was a Conan beginner, I worked hard to understand it through the manual, which was much shorter then, and even though many people had put lots of effort in to the manual, I am sorry to say that the sheer volume of information made it a rather frustrating and unsuccessful task, as I never wanted to be an expert - I just had a few simple tasks I needed to perform.
So whilst I'm not exactly saying that this statement is wrong, @melMass, I do find that there are more sympathetic ways of welcoming beginners to a project.
What I love about Dan's progress so far on the cheatsheet is that it is a clearly structured starting point, with minimal examples - and once there are links in the docs of each of the commands, it will be a fantastic start point to help those much less experienced with Conan to find which bits of the documentation it is worth their time to read first.
(The challenge with maintaining the cheatsheet over time will be avoiding the temptation to make it too long, so that it looses this benefit...)
The PDF of the Conan 1.35 manual runs to over 700 pages, and even starting to work your way around the conan docs is quite a daunting prospect.
You are completely right and it's especially hard in the case of conan as it can fit so many different configurations/arch/deployment systems but I think a single well-done sheet, like the one Dan started could benefit both user base, as you said linking to the doc would make it even more universal.
@danpetry I'll go through the whole sheet in the evening (GMT +1) and see if I can contribute, I do have notes of my own on a Notion sheet.
(The challenge with maintaining the cheatsheet over time will be avoiding the temptation to make it too long, so that it looses this benefit...)
seconded, I think it should stay fairly focused and not get too much longer, personally.
thanks for helping out, @melMass and @claremacrae !
I've just raised a PR: https://github.com/conan-io/docs/pull/2071. @melMass if you had some additions in the pipeline feel free to raise a PR against my branch, or maybe wait till it's merged and then make additions - up to you.
NB that I made some changes, rebased and force pushed this branch today... sorry for any inconvenience...
Both 1.x and 2.0 have cheetsheats now. 🚀
Thanks everyone who helped :)
