docs: bifurcate documentation into user and admin sections (#38196)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

docs/admin_docs/installation/pypi.mdx

@@ -0,0 +1,164 @@
+---
+title: PyPI
+hide_title: true
+sidebar_position: 4
+version: 1
+---
+
+import useBaseUrl from "@docusaurus/useBaseUrl";
+
+# Installing Superset from PyPI
+
+<img src={useBaseUrl("/img/pypi.png" )} width="150" />
+<br /><br />
+
+This page describes how to install Superset using the `apache_superset` package [published on PyPI](https://pypi.org/project/apache_superset/).
+
+## OS Dependencies
+
+Superset stores database connection information in its metadata database. For that purpose, we use
+the cryptography Python library to encrypt connection passwords. Unfortunately, this library has OS
+level dependencies.
+
+**Debian and Ubuntu**
+
+Ubuntu **24.04** uses python 3.12 per default, which currently is not supported by Superset. You need to add a second python installation of 3.11 and install the required additional dependencies.
+```bash
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt update
+sudo apt install python3.11 python3.11-dev python3.11-venv build-essential libssl-dev libffi-dev libsasl2-dev libldap2-dev default-libmysqlclient-dev
+```
+
+In Ubuntu **20.04 and 22.04** the following command will ensure that the required dependencies are installed:
+
+```bash
+sudo apt-get install build-essential libssl-dev libffi-dev python3-dev python3-pip libsasl2-dev libldap2-dev default-libmysqlclient-dev
+```
+
+In Ubuntu **before 20.04** the following command will ensure that the required dependencies are installed:
+
+```bash
+sudo apt-get install build-essential libssl-dev libffi-dev python-dev python-pip libsasl2-dev libldap2-dev default-libmysqlclient-dev
+```
+
+**Fedora and RHEL-derivative Linux distributions**
+
+Install the following packages using the `yum` package manager:
+
+```bash
+sudo yum install gcc gcc-c++ libffi-devel python-devel python-pip python-wheel openssl-devel cyrus-sasl-devel openldap-devel
+```
+
+In more recent versions of CentOS and Fedora, you may need to install a slightly different set of packages using `dnf`:
+
+```bash
+sudo dnf install gcc gcc-c++ libffi-devel python3-devel python3-pip python3-wheel openssl-devel cyrus-sasl-devel openldap-devel
+```
+
+Also, on CentOS, you may need to upgrade pip for the install to work:
+
+```bash
+pip3 install --upgrade pip
+```
+
+**Mac OS X**
+
+If you're not on the latest version of OS X, we recommend upgrading because we've found that many
+issues people have run into are linked to older versions of Mac OS X. After updating, install the
+latest version of XCode command line tools:
+
+```bash
+xcode-select --install
+```
+
+We don't recommend using the system installed Python. Instead, first install the
+[homebrew](https://brew.sh/) manager and then run the following commands:
+
+```bash
+brew install readline pkg-config libffi openssl mysql postgresql@14
+```
+
+You should install a recent version of Python. Refer to the
+[pyproject.toml](https://github.com/apache/superset/blob/master/pyproject.toml) file for a list of Python
+versions officially supported by Superset. We'd recommend using a Python version manager
+like [pyenv](https://github.com/pyenv/pyenv)
+(and also [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv)).
+
+Let's also make sure we have the latest version of `pip` and `setuptools`:
+
+```bash
+pip install --upgrade setuptools pip
+```
+
+Lastly, you may need to set LDFLAGS and CFLAGS for certain Python packages to properly build. You can export these variables with:
+
+```bash
+export LDFLAGS="-L$(brew --prefix openssl)/lib"
+export CFLAGS="-I$(brew --prefix openssl)/include"
+```
+
+These will now be available when pip installing requirements.
+
+## Python Virtual Environment
+
+We highly recommend installing Superset inside of a virtual environment.
+
+You can create and activate a virtual environment using the following commands. Ensure you are using a compatible version of python. You might have to explicitly use for example `python3.11` instead of `python3`.
+
+```bash
+# virtualenv is shipped in Python 3.6+ as venv instead of pyvenv.
+# See https://docs.python.org/3.6/library/venv.html
+python3 -m venv venv
+. venv/bin/activate
+```
+
+Or with pyenv-virtualenv:
+
+```bash
+# Here we name the virtual env 'superset'
+pyenv virtualenv superset
+pyenv activate superset
+```
+
+Once you activated your virtual environment, all of the Python packages you install or uninstall
+will be confined to this environment. You can exit the environment by running `deactivate` on the
+command line.
+
+### Installing and Initializing Superset
+
+First, start by installing `apache_superset`:
+
+```bash
+pip install apache_superset
+```
+
+Then, define mandatory configurations, SECRET_KEY and FLASK_APP:
+```bash
+export SUPERSET_SECRET_KEY=YOUR-SECRET-KEY # For production use, make sure this is a strong key, for example generated using `openssl rand -base64 42`. See https://superset.apache.org/admin-docs/configuration/configuring-superset#specifying-a-secret_key
+export FLASK_APP=superset
+```
+
+Then, you need to initialize the database:
+
+```bash
+superset db upgrade
+```
+
+Finish installing by running through the following commands:
+
+```bash
+# Create an admin user in your metadata database (use `admin` as username to be able to load the examples)
+superset fab create-admin
+
+# Load some data to play with
+superset load_examples
+
+# Create default roles and permissions
+superset init
+
+# To start a development web server on port 8088, use -p to bind to another port
+superset run -p 8088 --with-threads --reload --debugger
+```
+
+If everything worked, you should be able to navigate to `hostname:port` in your browser (e.g.
+locally by default at `localhost:8088`) and login using the username and password you created.