[Task] Design first-run experience

[lextm]

As we plan to revamp the ecosystem #708 maybe it's time to start designing first run experience and see what might be worked out.

Typical Setup

Everything can start from single folder setup, and virtual environment solutions can make it easier to troubleshoot.

Type	Python version	Related Issues	Comments
pipenv managed folder	3.8+	#734	This approach supports single Python version very well.
conda managed folder	3.8+	TODO: a new issue	TODO
poetry managed folder	3.8+	#735	This approach supports multiple Python versions, and is suitable for Python package authors.
venv managed folder	3.8+	TODO: a new issue	This approach lacks of many useful features compared to other virtual environment solutions.
a folder without venv	3.8+	TODO: a new issue	This approach might be used in simplest cases, and by beginners.

Complex Setup

TODO: Here we might track issues with a multi-folder workspace.

[alcarney]

I did briefly play with adding a "Getting started" walkthrough that you can find in the current pre-release - perhaps it just needs to be made more obvious?

[alcarney]

Is there much of a difference between venv, poetry and pipenv? Aren't they all virtual environments under the hood and since Esbonio relies on the Python extension, won't that handle most of the differences for us anyway?

[lextm]

"Getting started" walkthrough is a great idea, but I personally never finished one of them yet. You cannot force end users to click through the steps, and like I wrote even the manual steps aren't complex.

However, Microsoft Python extension, who handles virtual environment selection today, isn't perfect in several ways,

1. The popup list for environments isn't well ordered (or at least I didn't find its ordering logic useful) when you have for example 20+ environments.
2. Its support on various virtual environment solutions varies (and works pretty bad on poetry right now).
3. VS Code Python get started guide, as well as guides from the virtual environment solutions, rarely covers the exact steps a beginner should follow, and usually no sample repositories to present the ideal state.

So, at least for now I believe that extra work is on us, to fully understand how reStructuredText/sphinx/esbonio end users actually set up their machines for the tasks. Then we can move them towards a few typical step-by-step guides. That often reduces the troubleshooting efforts too, because you don't need to support every possible setup.

venv/poetry/pipenv, on the other hand, differ from each other significantly, and target different audience based on my personal experience. I mostly use pipenv for simple docs projects, and poetry if the docs project is associated with a Python package. In #734 and #735 I gave sample projects. I didn't use conda and personally dislike venv, so I didn't try to write instructions about them. I believe someone else might work on those in the future.

Note that I hit an issue with poetry/esbonio when switching among different environments for the same project folder and reported it in #732, so I do expect different virtual environment solutions lead to different user experience with esbonio.

[alcarney]

I see, so if I'm reading this right you're talking more about the end-user documentation for the different workflows rather than anything specific esbonio needs to handle from a technical standpoint? - Since (correct me if I'm wrong), while the tools differ greatly in usage, using them with esbonio boils down to passing the correct command to the esbonio.sphinx.pythonCommand option

[lextm]

you're talking more about the end-user documentation for the different workflows rather than anything specific esbonio needs to handle from a technical standpoint?

Correct. I thought that "first-run experience" is end user facing and about how to get them started with an extension as quickly as possible. So we have to

• Know what they did before installing the extension
  • Which virtual environment solution they use
  • Whether this is a pure docs project or with Python package
• Optimize the steps to configure right after installing the extension
  • Via "Getting started" walkthrough, or via https://docs.esbon.io, or via any other way.
  • Might need to coordinate among Python extensions (Microsoft Python, esbonio, and others) to unify and simplify the steps.

This experience design/implementation can involve both technical and non-technical tasks. And based on my previous experience, the non-technical part even matters more.

[alcarney]

I'm leaning towards building environment discovery logic into the language server... yes that duplicates some of the benefits we get from using the Python extension in VSCode, However, not doing this leaves all the other language clients on their own - plus it gives us a chance if VSCode tells the server the wrong thing on the first run.

I don't suppose there is an existing Python library for this? I didn't find anything after a very quick search, though I feel like it's something that should already exist?

[alcarney]

Something worth keeping an eye on: https://github.com/microsoft/python-environment-tools

Seems to be a tool that does exactly what we'd want, at the very least it might make environment discovery via the Python extension better...