scripts: sphinx-pre-install: add docstring documentation

scripts: sphinx-pre-install: add docstring documentation

This program is somewhat complex. Add some docstring documentation,
explaining what each function and class is supposed to do.

Most of the focus here were to describe the ancillary functions used
to detect dependency needs.

The main SphinxDependencyChecker still requires a lot of care,
and probably need to be reorganized to clearly split the 4 types
of output it produces:

- Need to upgrade Python binary;
- System install needs;
- Virtual env install needs;
- Python install needs via system packages, to run Sphinx
  natively.

Yet, for now, I'm happy of having it a lot better documented
than its Perl version.

-

While here, rename a parameter to have its usage better
documented.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0cadab2cab3f78ae6d9f378e92a45125fbc5188f.1754992972.git.mchehab+huawei@kernel.org