feat: Upgrade documentation V2

.rat-excludes

@@ -35,8 +35,9 @@ apache_superset.egg-info
 .*csv
 # Generated doc files
 env/*
-docs/README.md
 docs/.htaccess*
+docs-v2/.htaccess*
+.nojekyll
 _build/*
 _static/*
 .buildinfo

docs-v2/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs-v2/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "arrowParens": "avoid"
+}

docs-v2/README.md

@@ -0,0 +1,52 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+```
+$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs-v2/babel.config.js

@@ -0,0 +1,22 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs-v2/docs/Contributing/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Contributing",
+  "position": 6
+}

docs-v2/docs/Contributing/contributing-page.mdx

@@ -0,0 +1,21 @@
+---
+name: General Resources
+menu: Contributing
+route: /docs/contributing/contribution-guidelines
+index: 1
+version: 1
+---
+
+## Contributing to Superset
+
+Superset is an [Apache Software foundation](https://www.apache.org/theapacheway/index.html) project.
+The core contributors (or committers) to Superset communicate primarily in the following channels (all of
+which you can join):
+
+- [Mailing list](https://lists.apache.org/list.html?dev@superset.apache.org)
+- [Apache Superset Slack community](https://join.slack.com/t/apache-superset/shared_invite/zt-uxbh5g36-AISUtHbzOXcu0BIj7kgUaw)
+- [Github issues and PR's](https://github.com/apache/superset/issues)
+
+More references:
+- [Comprehensive Tutorial for Contributing Code to Apache Superset](https://preset.io/blog/tutorial-contributing-code-to-apache-superset/)
+- [CONTRIBUTING Guide on Github](https://github.com/apache/superset/blob/master/CONTRIBUTING.md)

docs-v2/docs/Contributing/conventions-and-typing.mdx

@@ -0,0 +1,57 @@
+---
+title: Conventions and Typing
+hide_title: true
+sidebar_position: 7
+version: 1
+---
+
+## Conventions
+
+### Python
+
+Parameters in the `config.py` (which are accessible via the Flask app.config dictionary) are assumed to always be defined and thus should be accessed directly via,
+
+```python
+blueprints = app.config["BLUEPRINTS"]
+```
+
+rather than,
+
+```python
+blueprints = app.config.get("BLUEPRINTS")
+```
+
+or similar as the later will cause typing issues. The former is of type `List[Callable]` whereas the later is of type `Optional[List[Callable]]`.
+
+## Typing
+
+### Python
+
+To ensure clarity, consistency, all readability, _all_ new functions should use
+[type hints](https://docs.python.org/3/library/typing.html) and include a
+docstring.
+
+Note per [PEP-484](https://www.python.org/dev/peps/pep-0484/#exceptions) no
+syntax for listing explicitly raised exceptions is proposed and thus the
+recommendation is to put this information in a docstring, i.e.,
+
+```python
+import math
+from typing import Union
+
+
+def sqrt(x: Union[float, int]) -> Union[float, int]:
+    """
+    Return the square root of x.
+
+    :param x: A number
+    :returns: The square root of the given number
+    :raises ValueError: If the number is negative
+    """
+
+    return math.sqrt(x)
+```
+
+### TypeScript
+
+TypeScript is fully supported and is the recommended language for writing all new frontend components. When modifying existing functions/components, migrating to TypeScript is appreciated, but not required. Examples of migrating functions/components to TypeScript can be found in [#9162](https://github.com/apache/superset/pull/9162) and [#9180](https://github.com/apache/superset/pull/9180).

docs-v2/docs/Contributing/hooks-and-linting.mdx

@@ -0,0 +1,61 @@
+---
+title: Pre-commit Hooks and Linting
+hide_title: true
+sidebar_position: 6
+version: 1
+---
+
+## Git Hooks
+
+Superset uses Git pre-commit hooks courtesy of [pre-commit](https://pre-commit.com/). To install run the following:
+
+```bash
+pip3 install -r requirements/integration.txt
+pre-commit install
+```
+
+A series of checks will now run when you make a git commit.
+
+Alternatively it is possible to run pre-commit via tox:
+
+```bash
+tox -e pre-commit
+```
+
+Or by running pre-commit manually:
+
+```bash
+pre-commit run --all-files
+```
+
+## Linting
+
+### Python
+
+We use [Pylint](https://pylint.org/) for linting which can be invoked via:
+
+```bash
+# for python
+tox -e pylint
+```
+
+In terms of best practices please advoid blanket disablement of Pylint messages globally (via `.pylintrc`) or top-level within the file header, albeit there being a few exceptions. Disablement should occur inline as it prevents masking issues and provides context as to why said message is disabled.
+
+Additionally the Python code is auto-formatted using [Black](https://github.com/python/black) which
+is configured as a pre-commit hook. There are also numerous [editor integrations](https://black.readthedocs.io/en/stable/editor_integration.html)
+
+### TypeScript
+
+```bash
+cd superset-frontend
+npm ci
+npm run lint
+```
+
+If using the eslint extension with vscode, put the following in your workspace `settings.json` file:
+
+```json
+"eslint.workingDirectories": [
+  "superset-frontend"
+]
+```

docs-v2/docs/Contributing/local-backend.mdx

@@ -0,0 +1,106 @@
+---
+title: Running a Local Flask Backend
+hide_title: true
+sidebar_position: 5
+version: 1
+---
+
+### Flask server
+
+#### OS Dependencies
+
+Make sure your machine meets the [OS dependencies](https://superset.apache.org/docs/installation/installing-superset-from-scratch#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.7 or 3.8, then proceed with:
+
+````bash
+# Create a virtual environment and activate it (recommended)
+python3 -m venv venv # setup a python3 virtualenv
+source venv/bin/activate
+
+# Install external dependencies
+pip install -r requirements/testing.txt
+
+# Install Superset in editable (development) mode
+pip install -e .
+
+# Initialize the database
+superset db upgrade
+
+# Create an admin user in your metadata database (use `admin` as username to be able to load the examples)
+superset fab create-admin
+
+# Create default roles and permissions
+superset init
+
+# Load some data to play with.
+# Note: you MUST have previously created an admin user with the username `admin` for this command to work.
+superset load-examples
+
+# Start the Flask dev web server from inside your virtualenv.
+# Note that your page may not have CSS at this point.
+FLASK_ENV=development superset run -p 8088 --with-threads --reload --debugger
+```
+
+Or you can install via our Makefile
+
+```bash
+# Create a virtual environment and activate it (recommended)
+$ python3 -m venv venv # setup a python3 virtualenv
+$ source venv/bin/activate
+
+# install pip packages + pre-commit
+$ make install
+
+# Install superset pip packages and setup env only
+$ make superset
+
+# Setup pre-commit only
+$ make pre-commit
+````
+
+**Note: the FLASK_APP env var should not need to be set, as it's currently controlled
+via `.flaskenv`, however if needed, it should be set to `superset.app:create_app()`**
+
+If you have made changes to the FAB-managed templates, which are not built the same way as the newer, React-powered front-end assets, you need to start the app without the `--with-threads` argument like so:
+`FLASK_ENV=development superset run -p 8088 --reload --debugger`
+
+#### Dependencies
+
+If you add a new requirement or update an existing requirement (per the `install_requires` section in `setup.py`) you must recompile (freeze) the Python dependencies to ensure that for CI, testing, etc. the build is deterministic. This can be achieved via,
+
+```bash
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ python3 -m pip install -r requirements/integration.txt
+$ pip-compile-multi --no-upgrade
+```
+
+#### Logging to the browser console
+
+This feature is only available on Python 3. When debugging your application, you can have the server logs sent directly to the browser console using the [ConsoleLog](https://github.com/betodealmeida/consolelog) package. You need to mutate the app, by adding the following to your `config.py` or `superset_config.py`:
+
+```python
+from console_log import ConsoleLog
+
+def FLASK_APP_MUTATOR(app):
+    app.wsgi_app = ConsoleLog(app.wsgi_app, app.logger)
+```
+
+Then make sure you run your WSGI server using the right worker type:
+
+```bash
+FLASK_ENV=development gunicorn "superset.app:create_app()" -k "geventwebsocket.gunicorn.workers.GeventWebSocketWorker" -b 127.0.0.1:8088 --reload
+```
+
+You can log anything to the browser console, including objects:
+
+```python
+from superset import app
+app.logger.error('An exception occurred!')
+app.logger.info(form_data)
+```
+
+### Frontend Assets
+See [Running Frontend Assets Locally](https://superset.apache.org/docs/installation/installing-superset-from-scratch#os-dependencies)