Promote how to install dependencies

[erlend-aasland]

Prior discussion:

• Put 'Install dependencies' before 'Compile and build' #1337

I opened PR #1337 since I was puzzled that we tell people how to configure and build CPython before we tell them how to install third party dependencies for extension modules like tkinter, sqlite3, and curses; in my mind, we should tell people how to install dependencies before we tell them how to configure and build CPython. I asked about this on Discord, and based on the responses, I created PR #1337. However, reordering these sections is controversial, so we need more discussion.

Arguments for keeping the current layout:

• historically, most extension modules were considered optional; for most uses this is also the case, so a simple process (configure, build) is better than a complex process (install deps, configure, build)

Arguments for reordering the layout:

• from time to time, we topics are opened on Discord and bug-reports are opened on the CPython repo where people complain that their CPython build "failed" because dependencies for some extension modules were not found; often, the answer to these reports is to point them to Install dependencies in the Devguide
• many people do not view the extension modules of the stdlib as optional; they expect the stdlib to be "complete" when they build CPython locally
• more advanced developers/users may expect a layout where dependencies are installed before one configure and build CPython

[erlend-aasland]

@ezio-melotti, please edit the OP if I misrepresented your arguments :)

[erlend-aasland]

cc. @nedbat

[erlend-aasland]

My initial proposal for how to promote the Install dependencies section was to simply reorder the Setup and building page so Install dependencies comes before Compile and build.

Other (and not necessarily conflicting) proposals are:

• In the Compile and build section, more clearly communicate that reading the Installing dependencies may be of interest for those who want a "full stdlib", before they proceed with configuring and building CPython
• In the build system, provide a less dramatic informational message when dependencies for a stdlib extension module are not found, and possibly also link to the Devguide in order to mitigate the problem

[ezio-melotti]

I suggest we do the following:

1. Add a "quick guide" at the top of the setup-building page (like the one in the "Lifecycle of a PR" page) which lists all the steps (including optional ones, marked as such) with links to the respective sections. This will give users a concise overview and provide a quick way to navigate the page and jump directly to the relevant section(s) (e.g. if they already have git installed). This might also need to be within tabs for the different operating systems.
2. Move the Installing dependencies section before the Compile and build section to keep things in order as it was suggested in the original PR. With the "quick guide" at the top, it will be easier to navigate the page and skip this section/step.
3. At the beginning of the Installing dependencies section, clarify when/why users might want to install the extra deps. After the clarification, add a "If you don't need the extra deps, you can skip to the Compile and build section" link.
4. Further clarify that missing deps are not necessarily a problem by improving the current message;

I also wonder if the whole Compile and build section could use tabs for the different operating systems. This will make the whole page shorter and easier to navigate, and the tab switching can also be synced with the "quick guide", so that once the user picked their OS they won't see other instructions that are not relevant to them.

[erlend-aasland]

I think all of your suggestions are worth doing, Ezio; thanks!