docs: Refactor Documentation Structure (apache#28161)

Co-authored-by: Evan Rusackas <[email protected]>
Co-authored-by: Sam Firke <[email protected]>

CONTRIBUTING.md

@@ -466,7 +466,7 @@ Commits to `master` trigger a rebuild and redeploy of the documentation site. Su
 
 #### OS Dependencies
 
-Make sure your machine meets the [OS dependencies](https://superset.apache.org/docs/installation/installing-superset-from-pypi#os-dependencies) before following these steps.
+Make sure your machine meets the [OS dependencies](https://superset.apache.org/docs/installation/pypi#os-dependencies) before following these steps.
 You also need to install MySQL or [MariaDB](https://mariadb.com/downloads).
 
 Ensure that you are using Python version 3.9, 3.10 or 3.11, then proceed with:

README.md

@@ -139,7 +139,7 @@ Want to add support for your datastore or data engine? Read more [here](https://
 
 ## Installation and Configuration
 
-[Extended documentation for Superset](https://superset.apache.org/docs/installation/installing-superset-using-docker-compose)
+[Extended documentation for Superset](https://superset.apache.org/docs/installation/docker-compose)
 
 ## Get Involved
 
@@ -171,10 +171,10 @@ Understanding the Superset Points of View
 
 
 - Getting Started with Superset
-  - [Superset in 2 Minutes using Docker Compose](https://superset.apache.org/docs/installation/installing-superset-using-docker-compose#installing-superset-locally-using-docker-compose)
+  - [Superset in 2 Minutes using Docker Compose](https://superset.apache.org/docs/installation/docker-compose#installing-superset-locally-using-docker-compose)
   - [Installing Database Drivers](https://superset.apache.org/docs/databases/docker-add-drivers/)
   - [Building New Database Connectors](https://preset.io/blog/building-database-connector/)
-  - [Create Your First Dashboard](https://superset.apache.org/docs/creating-charts-dashboards/first-dashboard)
+  - [Create Your First Dashboard](https://superset.apache.org/docs/using-superset/first-dashboard)
   - [Comprehensive Tutorial for Contributing Code to Apache Superset
   ](https://preset.io/blog/tutorial-contributing-code-to-apache-superset/)
 - [Resources to master Superset by Preset](https://preset.io/resources/)

RESOURCES/FEATURE_FLAGS.md

@@ -40,19 +40,19 @@ These features are **finished** but currently being tested. They are usable, but
 
 [//]: # "PLEASE KEEP THE LIST SORTED ALPHABETICALLY"
 
-- ALERT_REPORTS: [(docs)](https://superset.apache.org/docs/installation/alerts-reports)
+- ALERT_REPORTS: [(docs)](https://superset.apache.org/docs/configuration/alerts-reports)
 - ALLOW_FULL_CSV_EXPORT
 - CACHE_IMPERSONATION
 - CONFIRM_DASHBOARD_DIFF
 - DRILL_TO_DETAIL
-- DYNAMIC_PLUGINS: [(docs)](https://superset.apache.org/docs/installation/running-on-kubernetes)
+- DYNAMIC_PLUGINS: [(docs)](https://superset.apache.org/docs/configuration/running-on-kubernetes)
 - ENABLE_SUPERSET_META_DB: [(docs)](https://superset.apache.org/docs/databases/meta-database/)
 - ESTIMATE_QUERY_COST
 - GLOBAL_ASYNC_QUERIES [(docs)](https://github.com/apache/superset/blob/master/CONTRIBUTING.md#async-chart-queries)
 - HORIZONTAL_FILTER_BAR
 - PLAYWRIGHT_REPORTS_AND_THUMBNAILS
 - RLS_IN_SQLLAB
-- SSH_TUNNELING [(docs)](https://superset.apache.org/docs/installation/setup-ssh-tunneling)
+- SSH_TUNNELING [(docs)](https://superset.apache.org/docs/configuration/setup-ssh-tunneling)
 - USE_ANALAGOUS_COLORS
 
 ## Stable
@@ -69,18 +69,18 @@ These features flags are **safe for production**. They have been tested and will
 ### Flags retained for runtime configuration
 - ALERTS_ATTACH_REPORTS
 - ALLOW_ADHOC_SUBQUERY
-- DASHBOARD_RBAC [(docs)](https://superset.apache.org/docs/creating-charts-dashboards/first-dashboard#manage-access-to-dashboards)
+- DASHBOARD_RBAC [(docs)](https://superset.apache.org/docs/using-superset/first-dashboard#manage-access-to-dashboards)
 - DATAPANEL_CLOSED_BY_DEFAULT
 - DRUID_JOINS
 - EMBEDDABLE_CHARTS
 - EMBEDDED_SUPERSET
 - ENABLE_TEMPLATE_PROCESSING
 - ESCAPE_MARKDOWN_HTML
 - LISTVIEWS_DEFAULT_CARD_VIEW
-- SCHEDULED_QUERIES [(docs)](https://superset.apache.org/docs/installation/alerts-reports)
+- SCHEDULED_QUERIES [(docs)](https://superset.apache.org/docs/configuration/alerts-reports)
 - SQLLAB_BACKEND_PERSISTENCE
-- SQL_VALIDATORS_BY_ENGINE [(docs)](https://superset.apache.org/docs/installation/sql-templating)
-- THUMBNAILS [(docs)](https://superset.apache.org/docs/installation/cache)
+- SQL_VALIDATORS_BY_ENGINE [(docs)](https://superset.apache.org/docs/configuration/sql-templating)
+- THUMBNAILS [(docs)](https://superset.apache.org/docs/configuration/cache)
 
 ## Deprecated Flags
 

docs/docs/installation/alerts-reports.mdx → docs/docs/configuration/alerts-reports.mdx

@@ -20,7 +20,7 @@ Alerts and reports are disabled by default. To turn them on, you need to do some
 
 ##### In your `superset_config.py` or `superset_config_docker.py`
 
-- `"ALERT_REPORTS"` [feature flag](/docs/installation/configuring-superset#feature-flags) must be turned to True.
+- `"ALERT_REPORTS"` [feature flag](/docs/configuration/configuring-superset#feature-flags) must be turned to True.
 - `beat_schedule` in CeleryConfig must contain schedule for `reports.scheduler`.
 - At least one of those must be configured, depending on what you want to use:
   - emails: `SMTP_*` settings
@@ -35,7 +35,7 @@ Screenshots will be taken but no messages actually sent as long as `ALERT_REPORT
 - You must install a headless browser, for taking screenshots of the charts and dashboards. Only Firefox and Chrome are currently supported.
   > If you choose Chrome, you must also change the value of `WEBDRIVER_TYPE` to `"chrome"` in your `superset_config.py`.
 
-Note: All the components required (Firefox headless browser, Redis, Postgres db, celery worker and celery beat) are present in the *dev* docker image if you are following [Installing Superset Locally](/docs/installation/installing-superset-using-docker-compose/).
+Note: All the components required (Firefox headless browser, Redis, Postgres db, celery worker and celery beat) are present in the *dev* docker image if you are following [Installing Superset Locally](/docs/installation/docker-compose/).
 All you need to do is add the required config variables described in this guide (See `Detailed Config`).
 
 If you are running a non-dev docker image, e.g., a stable release like `apache/superset:3.1.0`, that image does not include a headless browser.  Only the `superset_worker` container needs this headless browser to browse to the target chart or dashboard.
@@ -47,7 +47,7 @@ You can either install and configure the headless browser - see "Custom Dockerfi
 
 To send alerts and reports to Slack channels, you need to create a new Slack Application on your workspace.
 
-1. Connect to your Slack workspace, then head to <https://api.slack.com/apps>.
+1. Connect to your Slack workspace, then head to [https://api.slack.com/apps].
 2. Create a new app.
 3. Go to "OAuth & Permissions" section, and give the following scopes to your app:
    - `incoming-webhook`
@@ -64,7 +64,7 @@ Note: when you configure an alert or a report, the Slack channel list takes chan
 #### Kubernetes-specific
 
 - You must have a `celery beat` pod running. If you're using the chart included in the GitHub repository under [helm/superset](https://github.com/apache/superset/tree/master/helm/superset), you need to put `supersetCeleryBeat.enabled = true` in your values override.
-- You can see the dedicated docs about [Kubernetes installation](/docs/installation/running-on-kubernetes) for more generic details.
+- You can see the dedicated docs about [Kubernetes installation](/docs/installation/kubernetes) for more details.
 
 #### Docker Compose specific
 

docs/docs/installation/cache.mdx → docs/docs/configuration/cache.mdx

@@ -77,11 +77,11 @@ Caching for SQL Lab query results is used when async queries are enabled and is
 Note that this configuration does not use a flask-caching dictionary for its configuration, but
 instead requires a cachelib object.
 
-See [Async Queries via Celery](/docs/installation/async-queries-celery) for details.
+See [Async Queries via Celery](/docs/configuration/async-queries-celery) for details.
 
 ### Caching Thumbnails
 
-This is an optional feature that can be turned on by activating it’s [feature flag](/docs/installation/configuring-superset#feature-flags) on config:
+This is an optional feature that can be turned on by activating it’s [feature flag](/docs/configuration/configuring-superset#feature-flags) on config:
 
 ```
 FEATURE_FLAGS = {

docs/docs/installation/sql-templating.mdx → docs/docs/configuration/sql-templating.mdx

@@ -10,7 +10,7 @@ version: 1
 ### Jinja Templates
 
 SQL Lab and Explore supports [Jinja templating](https://jinja.palletsprojects.com/en/2.11.x/) in queries.
-To enable templating, the `ENABLE_TEMPLATE_PROCESSING` [feature flag](/docs/installation/configuring-superset#feature-flags) needs to be enabled in
+To enable templating, the `ENABLE_TEMPLATE_PROCESSING` [feature flag](/docs/configuration/configuring-superset#feature-flags) needs to be enabled in
 `superset_config.py`. When templating is enabled, python code can be embedded in virtual datasets and
 in Custom SQL in the filter and metric controls in Explore. By default, the following variables are
 made available in the Jinja context:

docs/docs/contributing/local-backend.mdx

@@ -9,7 +9,7 @@ version: 1
 
 #### OS Dependencies
 
-Make sure your machine meets the [OS dependencies](/docs/installation/installing-superset-from-pypi#os-dependencies) before following these steps.
+Make sure your machine meets the [OS dependencies](/docs/installation/pypi#os-dependencies) before following these steps.
 You also need to install MySQL or [MariaDB](https://mariadb.com/downloads).
 
 Ensure that you are using Python version 3.10 or 3.11, then proceed with:

docs/docs/frequently-asked-questions.mdx

@@ -1,7 +1,7 @@
 ---
 title: Frequently Asked Questions
 hide_title: true
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 ## Frequently Asked Questions
@@ -59,7 +59,7 @@ We recommend reading the instructions in
 
 ### Can I upload and visualize CSV data?
 
-Absolutely! Read the instructions [here](/docs/creating-charts-dashboards/exploring-data) to learn
+Absolutely! Read the instructions [here](/docs/using-superset/exploring-data) to learn
 how to enable and use CSV upload.
 
 ### Why are my queries timing out?
@@ -146,7 +146,7 @@ SQLALCHEMY_DATABASE_URI = 'sqlite:////new/location/superset.db?check_same_thread
 ```
 
 You can read more about customizing Superset using the configuration file
-[here](/docs/installation/configuring-superset).
+[here](/docs/configuration/configuring-superset).
 
 ### What if the table schema changed?
 
@@ -267,7 +267,7 @@ Superset uses [Scarf](https://about.scarf.sh/) by default to collect basic telem
 We use the [Scarf Gateway](https://docs.scarf.sh/gateway/) to sit in front of container registries, the [scarf-js](https://about.scarf.sh/package-sdks) package to track `npm` installations, and a Scarf pixel to gather anonymous analytics on Superset page views.
 Scarf purges PII and provides aggregated statistics. Superset users can easily opt out of analytics in various ways documented [here](https://docs.scarf.sh/gateway/#do-not-track) and [here](https://docs.scarf.sh/package-analytics/#as-a-user-of-a-package-using-scarf-js-how-can-i-opt-out-of-analytics).
 Superset maintainers can also opt out of telemetry data collection by setting the `SCARF_ANALYTICS` environment variable to `false` in the Superset container (or anywhere Superset/webpack are run).
-Additional opt-out instructions for Docker users are available on the [Docker Installation](/docs/installation/installing-superset-using-docker-compose) page.
+Additional opt-out instructions for Docker users are available on the [Docker Installation](/docs/installation/docker-compose) page.
 
 ### Does Superset have an archive panel or trash bin from which a user can recover deleted assets?
 

docs/docs/installation/docker.mdx → docs/docs/installation/docker-builds.mdx

@@ -1,3 +1,10 @@
+---
+title: Docker Builds
+hide_title: true
+sidebar_position: 5
+version: 1
+---
+
 # Docker builds, images and tags
 
 The Apache Superset community extensively uses Docker for development, release,

docs/docs/installation/installing-superset-using-docker-compose.mdx → docs/docs/installation/docker-compose.mdx

@@ -1,5 +1,5 @@
 ---
-title: Installing Locally Using Docker Compose
+title: Docker Compose
 hide_title: true
 sidebar_position: 3
 version: 1

docs/docs/installation/running-on-kubernetes.mdx → docs/docs/installation/kubernetes.mdx

@@ -1,5 +1,5 @@
 ---
-title: Installing on Kubernetes
+title:  Kubernetes
 hide_title: true
 sidebar_position: 1
 version: 1
@@ -304,7 +304,7 @@ configOverrides:
 
 #### Enable Alerts and Reports
 
-For this, as per the [Alerts and Reports doc](/docs/installation/email-reports), you will need to:
+For this, as per the [Alerts and Reports doc](/docs/configuration/alerts-reports), you will need to:
 
 ##### Install a supported webdriver in the Celery worker
 

docs/docs/installation/installing-superset-from-pypi.mdx → docs/docs/installation/pypi.mdx

@@ -1,5 +1,5 @@
 ---
-title: Installing from PyPI
+title: PyPI
 hide_title: true
 sidebar_position: 2
 version: 1
@@ -136,7 +136,7 @@ superset db upgrade
 ```
 
 :::tip
-Note that some configuration is mandatory for production instances of Superset. In particular, Superset will not start without a user-specified value of SECRET_KEY. Please see [Configuring Superset](/docs/installation/configuring-superset).
+Note that some configuration is mandatory for production instances of Superset. In particular, Superset will not start without a user-specified value of SECRET_KEY. Please see [Configuring Superset](/docs/configuration/configuring-superset).
 :::
 
 Finish installing by running through the following commands:

docs/docs/installation/upgrading-superset.mdx

@@ -1,7 +1,7 @@
 ---
 title: Upgrading Superset
 hide_title: true
-sidebar_position: 8
+sidebar_position: 4
 version: 1
 ---
 

docs/docs/intro.mdx

@@ -14,8 +14,8 @@ geospatial charts.
 Here are a **few different ways you can get started with Superset**:
 
 - Try a [Quickstart deployment](/docs/quickstart), powered by [Docker Compose](https://docs.docker.com/compose/)
-- Install Superset [from PyPI](/docs/installation/installing-superset-from-pypi/)
-- Deploy Superset [with Kubernetes](/docs/installation/running-on-kubernetes)
+- Install Superset [from PyPI](/docs/installation/pypi/)
+- Deploy Superset [with Kubernetes](/docs/installation/kubernetes)
 - Download the [source code from Apache Foundation's website](https://dist.apache.org/repos/dist/release/superset/)
 
 #### Video Overview
@@ -54,7 +54,7 @@ Superset is also cloud-native in the sense that it is flexible and lets you choo
 - Results backend (Redis, S3, Memcached, etc.),
 - Caching layer (Redis, Memcached, etc.)
 
-Superset also works well with [event-logging](/docs/installation/event-logging/)
+Superset also works well with [event-logging](/docs/configuration/event-logging/)
 services like StatsD, NewRelic, and DataDog.
 
 Superset is currently run at scale at many companies. For example, Superset is run in Airbnb’s

docs/docs/quickstart.mdx

@@ -15,7 +15,7 @@ While we recommend using `Docker Compose` for a quick start in a sandbox-type
 environment and for other development-type use cases, **we
 do not recommend this setup for production**. For this purpose please
 refer to our
-[Installing on Kubernetes](/docs/installation/running-on-kubernetes/)
+[Installing on Kubernetes](/docs/installation/kubernetes/)
 page.
 :::
 
@@ -60,10 +60,10 @@ processes by running Docker Compose `stop` command. By doing so, you can avoid d
 ## What's next?
 
 From this point on, you can head on to:
-- [Create your first Dashboard](/docs/creating-charts-dashboards/creating-your-first-dashboard)
+- [Create your first Dashboard](/docs/using-superset/creating-your-first-dashboard)
 - [Connect to a Database](/docs/databases/installing-database-drivers)
-- [Using Docker Compose](/docs/installation/installing-superset-using-docker-compose)
-- [Configure Superset](/docs/installation/configuring-superset/)
-- [Installing on Kubernetes](/docs/installation/running-on-kubernetes/)
+- [Using Docker Compose](/docs/installation/docker-compose)
+- [Configure Superset](/docs/configuration/configuring-superset/)
+- [Installing on Kubernetes](/docs/installation/kubernetes/)
 
 Or just explore our [Documentation](https://superset.apache.org/docs/intro)!

docs/docs/security/cves.mdx

@@ -79,12 +79,12 @@ sidebar_position: 2
 
 #### Version 2.0.1
 
-| CVE            | Title                                                       |          Affected |
-|:---------------|:------------------------------------------------------------|------------------:|
-| CVE-2022-41703 | SQL injection vulnerability in adhoc clauses                | < 2.0.1 or <1.5.2 |
-| CVE-2022-43717 | Cross-Site Scripting on dashboards                          | < 2.0.1 or <1.5.2 |
-| CVE-2022-43718 | Cross-Site Scripting vulnerability on upload forms          | < 2.0.1 or <1.5.2 |
-| CVE-2022-43719 | Cross Site Request Forgery (CSRF) on accept, request access | < 2.0.1 or <1.5.2 |
-| CVE-2022-43720 | Improper rendering of user input                            | < 2.0.1 or <1.5.2 |
-| CVE-2022-43721 | Open Redirect Vulnerability                                 | < 2.0.1 or <1.5.2 |
-| CVE-2022-45438 | Dashboard metadata information leak                         | < 2.0.1 or <1.5.2 |
+| CVE            | Title                                                       |          Affected  |
+|:---------------|:------------------------------------------------------------|------------------: |
+| CVE-2022-41703 | SQL injection vulnerability in adhoc clauses                | < 2.0.1 or < 1.5.2 |
+| CVE-2022-43717 | Cross-Site Scripting on dashboards                          | < 2.0.1 or < 1.5.2 |
+| CVE-2022-43718 | Cross-Site Scripting vulnerability on upload forms          | < 2.0.1 or < 1.5.2 |
+| CVE-2022-43719 | Cross Site Request Forgery (CSRF) on accept, request access | < 2.0.1 or < 1.5.2 |
+| CVE-2022-43720 | Improper rendering of user input                            | < 2.0.1 or < 1.5.2 |
+| CVE-2022-43721 | Open Redirect Vulnerability                                 | < 2.0.1 or < 1.5.2 |
+| CVE-2022-45438 | Dashboard metadata information leak                         | < 2.0.1 or < 1.5.2 |

docs/docs/security/security.mdx

@@ -1,5 +1,5 @@
 ---
-title: Security
+title: Security Configurations
 hide_title: true
 sidebar_position: 1
 ---

docs/docs/creating-charts-dashboards/creating-your-first-dashboard.mdx → docs/docs/using-superset/creating-your-first-dashboard.mdx

@@ -27,7 +27,7 @@ your existing SQL-speaking database or data store.
 
 First things first, we need to add the connection credentials to your database to be able
 to query and visualize data from it. If you're using Superset locally via
-[Docker compose](/docs/installation/installing-superset-using-docker-compose), you can
+[Docker compose](/docs/installation/docker-compose), you can
 skip this step because a Postgres database, named **examples**, is included and
 pre-configured in Superset for you.
 
@@ -185,7 +185,7 @@ Access to dashboards is managed via owners (users that have edit permissions to
 Non-owner users access can be managed two different ways:
 
 1. Dataset permissions - if you add to the relevant role permissions to datasets it automatically grants implicit access to all dashboards that uses those permitted datasets
-2. Dashboard roles - if you enable **DASHBOARD_RBAC** [feature flag](/docs/installation/configuring-superset#feature-flags) then you be able to manage which roles can access the dashboard
+2. Dashboard roles - if you enable **DASHBOARD_RBAC** [feature flag](/docs/configuration/configuring-superset#feature-flags) then you be able to manage which roles can access the dashboard
    - Granting a role access to a dashboard will bypass dataset level checks. Having dashboard access implicitly grants read access to all the featured charts in the dashboard, and thereby also all the associated datasets.
    - If no roles are specified for a dashboard, regular **Dataset permissions** will apply.