Cuurently, there are huge gaps of information required by python new starters

[plastikfan]

Question

I thought (assumed), that cookietemple could be used to bootstrap a project's boilerplate for both cli applications and libraries. In practice this is not the case, unless I am mistaken (which I most probably am, but can't trace down this information, because its not in the docs)

To create a python library:

cookietemple create widget-lib

? Choose the project's domain:  lib
? Choose the project's primary language:  (Use arrow keys)
 » cpp

⚠️ notice here, that the only language option here is cpp. If I progress to the end of the process, it creates the project, but in a huge heap of errors. Since this is a cpp project, I will say no more about this, because I am only interested in Python (lib and cli).

So on the face of it, it appears I can not create a python lib with cookietemple. So how can I get the benefits of a cookietemple pre-constructed project boilerplate for a python lib?

Now onto a Python cli:

cookietemple create widget-cli

? Choose the project's primary language:  (Use arrow keys)
 » python
   java

🍪 Hoorah, we can select python. So again, complete this process and this time the project is created without errors. From chatting in discord, I have been made aware that building for a cli and library is the same thing (just use domain=cli); please document this somewhere. Having a lib option that doesnt work for python is confusing and misleading without having extra info, that does not appear to be present anywhere.

Looking into the generated project, the first thing I tried to do was build the project. Taking a look at the makefile, there is no target called build. The nearest item is a clean-build target, which essentially does very little in the context of needing to build the project. It wasn't until I scrolled down to the bottom of the make file that I noticed a non intuitive task name called dist, which is the task I was looking for. Why is this task called distand not build as one would expect, especially since there is a clean-build target?

The other big area of confusion is to do with poetry and conda for managing dependencies in the project and the environment. Please can we have this documented somewhere as this is totally confusing for new python devs. The problem is both conda & poetry can manage environments but to a new user it is not clear the distinction between the 2. Its not just a simple matter of reading the documentation of these 2 project because they appear to do the same thing and the differences are very subtle. It would be nice if guidelines on when to use poetry and conda were documented as, as it stands, I dont know for example what the difference is between poetry shell and conda activate for activating an environment. And to install dependencies, do we install them into the environment with conda or do we do it with poetry? And how do we distinguish between project dependencies and environment dependencies? I guess this is something I'll find out in the dev cycle, but I would prefer to learn about this type of thing up front, to avoid and minimise a miserable experience later on.

I have also noticed quite other inconsistences/confusion in the documentation like the use of tox vs nox.

Please don't get me wrong, this is a great project and I really commend you for the work you have done. Its just the few rough edges, is making this more difficult to use that it should be for those starting out on their python journies, like me.

[Imipenem]

@plastikfan First of all, thanks for your input here:

Having a lib option that doesnt work for python is confusing and misleading without having extra info

Guess this is mainly caused by the different wording cli and lib, cause we had to separate them somehow. We will document this as this seems to be confusing for some.

Why is this task called dist and not build as one would expect, especially since there is a clean-build target?

Interesting catch here. The original version of the project had such targets. But during development process we started to somehow "abandon" the Makefile, because we moved to poetry which provided most functionality out of the box. Will have a chat with @Zethson how we should proceed here.

use of tox vs nox

We do not use tox anymore, so the docs should be updated here.

The other big area of confusion is to do with poetry and conda for managing dependencies in the project and the environment. Please can we have this documented somewhere as this is totally confusing for new python devs.

IMO, this is not the scope and responsibility of cookietemple. cookietemple is a project development (and setup) tool for people, who are familiar with the very basics of (python) development. As we deliver poetry, we can make some reference-links from the docs to poetry docs, but this should not be part of the cookietemple docs itsself, since its not in the scope. This goes esepcially for conda.