Clarify what it means to use menuinst for 'adding a shortcut to a package', and related documentation update

Checklist

[X] I added a descriptive title
[X] I searched open reports and couldn't find a duplicate

What happened?

I have installed (and regularly updated) the latest version of miniconda3 on my Windows (10) computer, and I automatically got a Miniconda3 folder in my Windows start menu, with links/shortcuts to Anaconda Prompt and Anaconda Powershell Prompt, that will open a terminal with the base environment initialized, and I'm now looking for a clean way to:

create shortcuts that will directly select an existing Python environment different from base
add Windows Terminal profiles to easily open the base or another existing environment from a Windows terminal (see #196)

I think using menuinst is the way to do this, but I'm still struggling with the existing documentation

conda website is slightly out of date ?

The Adding Windows Start menu items page:

still gives a link to the the menuinst wiki instead of the menuinst documentation
says When a package is installed, it can add a shortcut to the Windows Start menu. I guess menuinst can be used to create shortcuts to any application, but in the Python/conda case, isn't menuinst supposed to be used to create shortcuts to a Python environment? I mean, it makes sense to create a shortcut to the base environment, it makes no sense to create a shortcut to the numpy package

menuinst GH page 'package' ambiguity

menuinst GH page

There is the same ambiguity with the package word as on the website. Unless I have really missed an important point

menu item installation for conda packages. Do you mean conda environments?
If a conda package ships [...] invoke menuinst to [...] install the menu items

menuinst documentation website

The description is better as it says a tool which allows creating menu items or shortcuts to launch applications across operating systems

there is a section for shortcut names for base and non-base environments
but there is also a section for Adding shortcuts to conda packages !

I'm going to read the menuinst documentation again more carefully, and try to find out how to do what I wanted to do in the first place, that is easily select and use Python environments from the Windows start menu and from Windows Terminal

I'd rather not edit a json file to do that, but maybe there is no escaping this for now, and what is missing is a bin/menuinst CLI that would easily allow end users (and new Python users) to deal with environments

Additional Context

No response

menu item installation for conda packages. Do you mean conda environments?

No, conda packages is correct. While it doesn't make sense to create a shortcut for numpy, there are packages where it does make sense because they have a GUI. However, menuinst does not need conda at all, it's just used by conda. It can also create shortcuts to any file you like.

Using json files is essential to define your shortcuts. This is what happens when installing conda packages that have these config files:

The json files are copied into the Menu directory inside the conda environment.
conda specifically looks for those json files and invokes menuinst to read those config files and create the shortcut.

If you are using vanilla python, you can invoke the menuinst API directly.

What is indeed incomplete in the README.md file is the emphasis on "conda packages" - menuinst is not exclusive to conda packages, its API can be used directly without requiring conda.

conda / menuinst