Skip to content

Commit

Permalink
feat: Upgrade documentation V2 (apache#17411)
Browse files Browse the repository at this point in the history
* 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 <corbin@Corbins-MacBook-Pro.local>

* 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 <corbin@Corbins-MacBook-Pro.local>

* 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 <corbin@Corbins-MacBook-Pro.local>

* 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 <dungdm93@live.com>

* 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 <dungdm93@live.com>

* docs: Trino Authentications

Signed-off-by: Đặng Minh Dũng <dungdm93@live.com>

* 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 <kamil.gabryjelski@gmail.com>

* fix generator reference

* add steps to tutorial and fix package version

* refine docs/readme

Co-authored-by: Kamil Gabryjelski <kamil.gabryjelski@gmail.com>

* 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 <55605634+lyndsiWilliams@users.noreply.github.com>

Co-authored-by: Lyndsi Kay Williams <55605634+lyndsiWilliams@users.noreply.github.com>

* 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 <arash.afghahi@gmail.com>

* 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 <dungdm93@live.com>

* important change to MakeFile (apache#18037)

* add missing is_timeseries to pivot op

Co-authored-by: Erik Ritter <erik.ritter@airbnb.com>
Co-authored-by: Grace Guo <grace.guo@airbnb.com>
Co-authored-by: Đặng Minh Dũng <dungdm93@live.com>
Co-authored-by: AAfghahi <48933336+AAfghahi@users.noreply.github.com>

* 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 <jayakrishnan.karolil@nielsen.com>

* 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 <grace.guo@airbnb.com>
Co-authored-by: Đặng Minh Dũng <dungdm93@live.com>
Co-authored-by: AAfghahi <48933336+AAfghahi@users.noreply.github.com>
Co-authored-by: Hugh A. Miles II <hughmil3s@gmail.com>
Co-authored-by: ofekisr <35701650+ofekisr@users.noreply.github.com>
Co-authored-by: Ville Brofeldt <33317356+villebro@users.noreply.github.com>
Co-authored-by: Kamil Gabryjelski <kamil.gabryjelski@gmail.com>
Co-authored-by: Yongjie Zhao <yongjie.zhao@gmail.com>
Co-authored-by: Stephen Liu <750188453@qq.com>
Co-authored-by: Lyndsi Kay Williams <55605634+lyndsiWilliams@users.noreply.github.com>
Co-authored-by: Adam Dobrawy <ad-m@users.noreply.github.com>
Co-authored-by: Beto Dealmeida <roberto@dealmeida.net>
Co-authored-by: Emily Wu <86927881+em0227@users.noreply.github.com>
Co-authored-by: Josue Lugaro <82119536+JosueLugaro@users.noreply.github.com>
Co-authored-by: Arash <arash.afghahi@gmail.com>
Co-authored-by: Ville Brofeldt <ville.v.brofeldt@gmail.com>
Co-authored-by: Daniel Vaz Gaspar <danielvazgaspar@gmail.com>
Co-authored-by: Elizabeth Thompson <eschutho@gmail.com>
Co-authored-by: Michael S. Molina <70410625+michael-s-molina@users.noreply.github.com>
Co-authored-by: Erik Ritter <erik.ritter@airbnb.com>
Co-authored-by: Hammad-Raza <hammadraza42@hotmail.com>
Co-authored-by: jayakrishnankk <kk.jayakrishnan@gmail.com>
Co-authored-by: Jayakrishnan Karolil <jayakrishnan.karolil@nielsen.com>
Co-authored-by: Farid Rener <proteusvacuum@users.noreply.github.com>

* remove unneeded requirement

Co-authored-by: Corbin Robb <31329271+corbinrobb@users.noreply.github.com>
Co-authored-by: Corbin Robb <corbin@Corbins-MacBook-Pro.local>
Co-authored-by: Daniel W <61300812+The-hyphen-user@users.noreply.github.com>
Co-authored-by: Geido <60598000+geido@users.noreply.github.com>
Co-authored-by: Srini Kadamati <skadamat@gmail.com>
Co-authored-by: Grace Guo <grace.guo@airbnb.com>
Co-authored-by: Đặng Minh Dũng <dungdm93@live.com>
Co-authored-by: AAfghahi <48933336+AAfghahi@users.noreply.github.com>
Co-authored-by: ofekisr <35701650+ofekisr@users.noreply.github.com>
Co-authored-by: Ville Brofeldt <33317356+villebro@users.noreply.github.com>
Co-authored-by: Kamil Gabryjelski <kamil.gabryjelski@gmail.com>
Co-authored-by: Yongjie Zhao <yongjie.zhao@gmail.com>
Co-authored-by: Stephen Liu <750188453@qq.com>
Co-authored-by: Lyndsi Kay Williams <55605634+lyndsiWilliams@users.noreply.github.com>
Co-authored-by: Adam Dobrawy <ad-m@users.noreply.github.com>
Co-authored-by: Beto Dealmeida <roberto@dealmeida.net>
Co-authored-by: Emily Wu <86927881+em0227@users.noreply.github.com>
Co-authored-by: Josue Lugaro <82119536+JosueLugaro@users.noreply.github.com>
Co-authored-by: Arash <arash.afghahi@gmail.com>
Co-authored-by: Ville Brofeldt <ville.v.brofeldt@gmail.com>
Co-authored-by: Daniel Vaz Gaspar <danielvazgaspar@gmail.com>
Co-authored-by: Elizabeth Thompson <eschutho@gmail.com>
Co-authored-by: Michael S. Molina <70410625+michael-s-molina@users.noreply.github.com>
Co-authored-by: Erik Ritter <erik.ritter@airbnb.com>
Co-authored-by: Hammad-Raza <hammadraza42@hotmail.com>
Co-authored-by: jayakrishnankk <kk.jayakrishnan@gmail.com>
Co-authored-by: Jayakrishnan Karolil <jayakrishnan.karolil@nielsen.com>
Co-authored-by: Farid Rener <proteusvacuum@users.noreply.github.com>
  • Loading branch information
1 parent 186a08a commit 51df065
Show file tree
Hide file tree
Showing 204 changed files with 41,392 additions and 1 deletion.
3 changes: 2 additions & 1 deletion .rat-excludes
Expand Up @@ -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
Expand Down
20 changes: 20 additions & 0 deletions 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*
5 changes: 5 additions & 0 deletions docs-v2/.prettierrc
@@ -0,0 +1,5 @@
{
"singleQuote": true,
"trailingComma": "all",
"arrowParens": "avoid"
}
52 changes: 52 additions & 0 deletions 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.
22 changes: 22 additions & 0 deletions 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')],
};
4 changes: 4 additions & 0 deletions docs-v2/docs/Contributing/_category_.json
@@ -0,0 +1,4 @@
{
"label": "Contributing",
"position": 6
}
21 changes: 21 additions & 0 deletions 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)
57 changes: 57 additions & 0 deletions 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).
61 changes: 61 additions & 0 deletions 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"
]
```
106 changes: 106 additions & 0 deletions 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)

0 comments on commit 51df065

Please sign in to comment.