feat: Upgrade documentation V2 (apache#17411)

* setup docusaurus * rename * add introduction content * chore(docsV2): move content from docs to docsV2 (apache#17714) * add FAQs and contribution pages * chore: add api, security, and roadmap pages, include swaggerui in dependency for api page * chore: move api page header below imports * chore: change API page info alert to use built in Infima class instead of custom class Co-authored-by: Corbin Robb <[email protected]> * chore(docs-v2): moving more markdown content to new documentation site (apache#17736) * chore: move markdown content and images for docs installation directory to docs-v2 * chore: move docs miscellaneous directory content to docs-v2 * chore(docs-v2): move over connecting to databases content and rename some files to .mdx Co-authored-by: Corbin Robb <[email protected]> * Update styling and logo (apache#17990) * update styling * update colors * chore(docs-v2): remove blog and tutorial and update some styling (apache#17929) * add superset logo and favicon, change styles to better match current docs, add prettierrc * change file types to mdx * Add simple superset dark mode freindly logo * clean up default pages - blog and tutorial docs Co-authored-by: Corbin Robb <[email protected]> * Chore: moving charts and dashboard to docusaurus (apache#18036) * add contributing add creating charts and dashboards * delete extra images * update rat-excludes * Port homepage (apache#18115) * Port community page (apache#18128) * chore: add seo redirects for Docs v@ (apache#18092) * fix: handle null values in time-series table (apache#18039) * cleanup column_type_mappings (apache#17569) Signed-off-by: Đặng Minh Dũng <[email protected]> * important change to MakeFile (apache#18037) * Update superset-e2e.yml (apache#18041) * Revert "Update superset-e2e.yml (apache#18041)" (apache#18051) This reverts commit b565273. * feat: Trino Authentications (apache#17593) * feat: support Trino Authentications Signed-off-by: Đặng Minh Dũng <[email protected]> * docs: Trino Authentications Signed-off-by: Đặng Minh Dũng <[email protected]> * chore(supeset.utils.core): move all database utils to database utils module (apache#18058) * chore(plugin-chart-echarts): add types to controls (apache#18059) * fix(generator): more cleanup to plugin framework (apache#18027) * fix(generator): more cleanup to plugin framework * fix typo and package name * add docs * fix typo * Update superset-frontend/webpack.config.js Co-authored-by: Kamil Gabryjelski <[email protected]> * fix generator reference * add steps to tutorial and fix package version * refine docs/readme Co-authored-by: Kamil Gabryjelski <[email protected]> * feat(advanced analytics): support groupby in resample (apache#18045) * fix(dashboard): scope of nativefilter not update (apache#18048) * fix(generator): add lockfile and fix styling issues (apache#18073) * fix(generator): add lockfile and fix styling issues * fix margins and remove redundant scroll * update tutorial * refactor(sql_lab): SQL Lab Persistent Saved State (apache#17771) * a lot of console logs * testing * test * added saved_query to remoteId * created useEffect so that title properly changes in modal * Update superset-frontend/src/SqlLab/actions/sqlLab.js Co-authored-by: Lyndsi Kay Williams <[email protected]> Co-authored-by: Lyndsi Kay Williams <[email protected]> * refactor(example_data): replace the way the birth_names data is loaded to DB (apache#18060) * refactor: replace the way the birth_names data is loaded to DB * fix failed unit test * fix failed unit test * fix failed tests * fix pass wrong flag of support datetime type * remove unused fixture * feat: add chart description in info tooltip (apache#17207) * feat: add chart list description * fix: text overflow * fix: text-overflow with line-height * Correction of proper names format in README (apache#18087) * chore: added SEO routes * fix can't use examples helpers on non app context based environment (apache#18086) * chore: split CLI into multiple files (apache#18082) * chore: split CLI into multiple files * Update tests * Who fixes the fixtures? * Add subcommands dynamically * Rebase * fix misspelling (apache#18097) * refactor: sqleditorleftbar to functional (apache#17807) * Working on converting sqleditorleftbar to functional component * Creating draft PR to address bug * Still working on solving re rendering bug * infinite rerender fix * Creating draft PR to address bug * Cleaning up in preparation for push * Made changes suggested by Elizabeth * Fixed issues as per Lindsey's comment Co-authored-by: Arash <[email protected]> * fix rat excludes and headers * fix(docs): fix path of image for "Create New Chart" (apache#18089) * Migrate Checkbox story to tsx - see apache#18100 (apache#18101) Looks good! * refactor: migrate RowCountLabel to TypeScript & added story (apache#18105) * enable superbook for explore component * migrate RowCountLabel to TypeScript * add storybook for RowCountLabel * fix: logging warning on dataframe (don't use python's warnings) (apache#18111) * fix: logging warning on dataframe (don't use python's warnings) * lint * update changelog and updating for 1.4.0 (apache#18083) * feat: Adds a key-value endpoint to store charts form data (apache#17882) * feat: Adds a key-value endpoint to store charts form data * Fixes linting problems * Removes the query_params from the endpoints * Refactors the commands * Removes unused imports * Changes the parameters to use dataclass * Adds more access tests * Gets the first dataset while testing * Adds unit tests for the check_access function * Changes the can_access check * Always check for dataset access * fix(explore): fix chart embed code modal glitch (apache#17843) * feat(plugin-chart-echarts): support non-timeseries x-axis (apache#17917) * feat(plugin-chart-echarts): support non-timeseries x-axis * fix tests * change formula return type from Date to number * add x_axis test coverage * rename func and improve coverage * add x-axis control to bar chart * remove redundant console.log * fix description * make x-axis control mandatory * 🙃 * fix x-axis formatter * fix showValues * fix implicit rDTTM_ALIAS references in postProcessing * replace TIME_COLUMN with DTTM_ALIAS * fix remaining implicit indexes * fix: Disable filtering on wide result sets (apache#18021) * fix: handle null values in time-series table (apache#18039) * cleanup column_type_mappings (apache#17569) Signed-off-by: Đặng Minh Dũng <[email protected]> * important change to MakeFile (apache#18037) * add missing is_timeseries to pivot op Co-authored-by: Erik Ritter <[email protected]> Co-authored-by: Grace Guo <[email protected]> Co-authored-by: Đặng Minh Dũng <[email protected]> Co-authored-by: AAfghahi <[email protected]> * feat(country-map): added new countries in country-chart-map (apache#18081) * chore: migrating storybook jsx to typescript apache#18100 (apache#18133) * Migrating storybook jsx to typescript apache#18100 * Migrating storybook jsx to typescript Co-authored-by: Jayakrishnan Karolil <[email protected]> * feat(annotation): add toast feedback to annotation templates (apache#18116) * feat(dashboard): add toast feedback to dashboard actions (apache#18114) * feat(explore): more toast feedback on user actions in Explore (apache#18108) * feat(explore): add toasts feedback when user copies chart url * Show toast message when updating chart properties * Change toast type to success when saving chart * Use success toast from props * Fix tests * Use withToasts instead of dispatch * Use PropertiesModalProps instead of any * Docs: fix typo (apache#18125) * fix: undefined error when adding extra sequential color scheme (apache#18152) * feat: allow assets to be managed externally (apache#18093) * feat: allow assets to be managed externally * Use server_default * chore: use pkg_resources for cleaner config (apache#18130) * refactor: Moves the Explore form_data endpoint (apache#18151) * refactor: Moves the Explore form_data endpoint * Removes unused imports * Fixes openapi schema error * Fixes typo * Renames and UPDATING.md Co-authored-by: Grace Guo <[email protected]> Co-authored-by: Đặng Minh Dũng <[email protected]> Co-authored-by: AAfghahi <[email protected]> Co-authored-by: Hugh A. Miles II <[email protected]> Co-authored-by: ofekisr <[email protected]> Co-authored-by: Ville Brofeldt <[email protected]> Co-authored-by: Kamil Gabryjelski <[email protected]> Co-authored-by: Yongjie Zhao <[email protected]> Co-authored-by: Stephen Liu <[email protected]> Co-authored-by: Lyndsi Kay Williams <[email protected]> Co-authored-by: Adam Dobrawy <[email protected]> Co-authored-by: Beto Dealmeida <[email protected]> Co-authored-by: Emily Wu <[email protected]> Co-authored-by: Josue Lugaro <[email protected]> Co-authored-by: Arash <[email protected]> Co-authored-by: Ville Brofeldt <[email protected]> Co-authored-by: Daniel Vaz Gaspar <[email protected]> Co-authored-by: Elizabeth Thompson <[email protected]> Co-authored-by: Michael S. Molina <[email protected]> Co-authored-by: Erik Ritter <[email protected]> Co-authored-by: Hammad-Raza <[email protected]> Co-authored-by: jayakrishnankk <[email protected]> Co-authored-by: Jayakrishnan Karolil <[email protected]> Co-authored-by: Farid Rener <[email protected]> * remove unneeded requirement Co-authored-by: Corbin Robb <[email protected]> Co-authored-by: Corbin Robb <[email protected]> Co-authored-by: Daniel W <[email protected]> Co-authored-by: Geido <[email protected]> Co-authored-by: Srini Kadamati <[email protected]> Co-authored-by: Grace Guo <[email protected]> Co-authored-by: Đặng Minh Dũng <[email protected]> Co-authored-by: AAfghahi <[email protected]> Co-authored-by: ofekisr <[email protected]> Co-authored-by: Ville Brofeldt <[email protected]> Co-authored-by: Kamil Gabryjelski <[email protected]> Co-authored-by: Yongjie Zhao <[email protected]> Co-authored-by: Stephen Liu <[email protected]> Co-authored-by: Lyndsi Kay Williams <[email protected]> Co-authored-by: Adam Dobrawy <[email protected]> Co-authored-by: Beto Dealmeida <[email protected]> Co-authored-by: Emily Wu <[email protected]> Co-authored-by: Josue Lugaro <[email protected]> Co-authored-by: Arash <[email protected]> Co-authored-by: Ville Brofeldt <[email protected]> Co-authored-by: Daniel Vaz Gaspar <[email protected]> Co-authored-by: Elizabeth Thompson <[email protected]> Co-authored-by: Michael S. Molina <[email protected]> Co-authored-by: Erik Ritter <[email protected]> Co-authored-by: Hammad-Raza <[email protected]> Co-authored-by: jayakrishnankk <[email protected]> Co-authored-by: Jayakrishnan Karolil <[email protected]> Co-authored-by: Farid Rener <[email protected]>
casual-precision · Feb 10, 2022 · e944d51 · e944d51
1 parent 0fa260b
commit e944d51
Show file tree

Hide file tree

Showing 204 changed files with 41,392 additions and 1 deletion.
diff --git a/.rat-excludes b/.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

diff --git a/docs-v2/.gitignore b/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*
diff --git a/docs-v2/.prettierrc b/docs-v2/.prettierrc
@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "arrowParens": "avoid"
+}
diff --git a/docs-v2/README.md b/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.
diff --git a/docs-v2/babel.config.js b/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')],
+};
diff --git a/docs-v2/docs/Contributing/_category_.json b/docs-v2/docs/Contributing/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Contributing",
+  "position": 6
+}
diff --git a/docs-v2/docs/Contributing/contributing-page.mdx b/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/[email protected])
+- [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)
diff --git a/docs-v2/docs/Contributing/conventions-and-typing.mdx b/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).
diff --git a/docs-v2/docs/Contributing/hooks-and-linting.mdx b/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"
+]
+```
diff --git a/docs-v2/docs/Contributing/local-backend.mdx b/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)