Improve documentation on the behaviour of update and install

I believe that the documentation could be improved regarding what update and install are doing.

To me it is not really clear, for example:

• when doing update are the new packages installed? is the pyproject.toml file update with latest version numbers?
• when should one do install ? Only the first time?

Maybe we could collect here answers to questions like the two above and I’ll be happy to make a PR for the doc.

[finswimmer]

The purpose of poetry install is to:

• create a venv if None exists
• resolve dependency and write the exact version to poetry.lock if None exists
• install the locked dependencies in the venv
• install the current project in editable mode

A poetry install is only necessary if you:

• create the venv the first time
• change any metadata of the project, like version number
• add “scripts” entry points to the pyproject.toml

The purpose of poetry update is to:

• update all dependencies to the current version within in the pyproject.toml specified version range
• write the updated version to poetry.lock
• the version numbers in pyproject.toml remain untouched

[rafrafek]

Yes, they are installed by default using Poetry (but not captured by tools that build/install as a Python package).

Can we add this information to the docs here: https://python-poetry.org/docs/cli/#install