From d976154b3b63e89cd6c4300eb9ea253047f8ef31 Mon Sep 17 00:00:00 2001
From: Maxime Beauchemin <maximebeauchemin@gmail.com>
Date: Wed, 13 Mar 2024 10:33:24 -0700
Subject: [PATCH] more docs

---
 CONTRIBUTING.md                                 |  2 +-
 docs/docs/installation/configuring-superset.mdx | 13 +++++++++++++
 requirements/pip-compile-superset.py            | 16 +++++++++-------
 3 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8bdd9c0a32be9..b131b057b071c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -566,7 +566,7 @@ To bring all dependencies up to date as per the restrictions defined
 in `pyproject.toml`, simply run:
 
 ```bash
-$ ./requirements/pip-compile-superset.sh
+$ ./requirements/pip-compile-superset.py compile-deps
 ```
 
 #### Logging to the browser console
diff --git a/docs/docs/installation/configuring-superset.mdx b/docs/docs/installation/configuring-superset.mdx
index 30bc2f281cd36..8e3d6e88696eb 100644
--- a/docs/docs/installation/configuring-superset.mdx
+++ b/docs/docs/installation/configuring-superset.mdx
@@ -363,3 +363,16 @@ FEATURE_FLAGS = {
 ```
 
 A current list of feature flags can be found in [RESOURCES/FEATURE_FLAGS.md](https://github.com/apache/superset/blob/master/RESOURCES/FEATURE_FLAGS.md).
+
+
+### Extra python dependencies
+
+It's common for some environments to have specific python dependencies requirements. Maybe
+you need a set of extra libraries, or maybe you need to install specific versions for some
+libraries.
+
+First, we recommend you reuse the set of pinned dependencies we run CI and use throughout
+the ecosystem, located at `requirements/base.txt`. Now if you'd like expand on what's there
+the simple CLI located at `requirements/pip-compile-superset.py` can support you in doing so.
+See the `merge-compile` subcommand and `requirements/requirements-custom-example.in` for more
+details.
diff --git a/requirements/pip-compile-superset.py b/requirements/pip-compile-superset.py
index 0c12b84dbe7b9..f9e86cdedd0ef 100755
--- a/requirements/pip-compile-superset.py
+++ b/requirements/pip-compile-superset.py
@@ -110,24 +110,26 @@ def install_deps(dev: bool) -> None:
 @click.command()
 @click.argument("file1", type=click.Path(exists=True), default=BASE_REQS)
 @click.argument("file2", type=click.Path(exists=True), default=DEV_REQS)
-def compare_versions(file1: str, file2: str) -> None:
+@click.option("--verbose", is_flag=True, help="Enables verbose mode")
+def compare_versions(file1: str, file2: str, verbose: bool = False) -> None:
     """Load two requirements files, compare them, and print differences."""
     reqs1 = read_requirements(file1)
     reqs2 = read_requirements(file2)
     added, removed, version_changed = compare_requirements(reqs1, reqs2)
 
-    if added:
-        click.echo("Added:")
+    if added and verbose:
+        click.echo(f"Only in {file2}:")
         for lib, ver in added.items():
             click.echo(f"{lib}=={ver}")
-    if removed:
-        click.echo("\nRemoved:")
+    if removed and verbose:
+        click.echo(f"Only in {file1}:")
         for lib, ver in removed.items():
             click.echo(f"{lib}=={ver}")
     if version_changed:
-        click.echo("\nVersion Changed:")
+        click.secho("Common lib version mismatch:", fg="red")
         for lib, versions in version_changed.items():
-            click.echo(f"{lib}: from {versions[0]} to {versions[1]}")
+            click.secho(f"{lib}: from {versions[0]} to {versions[1]}", fg="red")
+        sys.exit(1)
 
 
 @click.command()