This is an automated email from the ASF dual-hosted git repository.
rusackas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git
The following commit(s) were added to refs/heads/master by this push:
new fadf0ec5ad Update documentation on updating documentation. (#20400)
fadf0ec5ad is described below
commit fadf0ec5ad74dc3f21eb099b4defe5ed5ec0b449
Author: Cody Leff <[email protected]>
AuthorDate: Thu Jun 16 15:05:37 2022 -0600
Update documentation on updating documentation. (#20400)
---
CONTRIBUTING.md | 34 +++++++++++++++++++++-------------
docs/README.md | 34 +---------------------------------
2 files changed, 22 insertions(+), 46 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 653cfe41a5..b94aeea569 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -160,7 +160,7 @@ Look through the GitHub issues. Issues tagged with
Superset could always use better documentation,
whether as part of the official Superset docs,
-in docstrings, `docs/*.rst` or even on the web as blog posts or
+in docstrings, or even on the web as blog posts or
articles. See [Documentation](#documentation) for more details.
### Add Translations
@@ -388,23 +388,30 @@ cd superset
The latest documentation and tutorial are available at
https://superset.apache.org/.
-The site is written using the Gatsby framework and docz for the
-documentation subsection. Find out more about it in `docs/README.md`
+The documentation site is built using [Docusaurus 2](https://docusaurus.io/),
a modern static website generator, the source for which resides in `./docs`.
-#### Images
+#### Local Development
-If you're adding new images to the documentation, you'll notice that the images
-referenced in the rst, e.g.
+To set up a local development environment with hot reloading for the
documentation site:
- .. image:: _static/images/tutorial/tutorial_01_sources_database.png
+```shell
+cd docs
+yarn install # Installs NPM dependencies
+yarn start # Starts development server at http://localhost:3000
+```
+
+#### Build
+
+To create and serve a production build of the documentation site:
-aren't actually stored in that directory. Instead, you should add and commit
-images (and any other static assets) to the
`superset-frontend/src/assets/images` directory.
-When the docs are deployed to https://superset.apache.org/, images
-are copied from there to the `_static/images` directory, just like they're
referenced
-in the docs.
+```shell
+yarn build
+yarn serve
+```
+
+#### Deployment
-For example, the image referenced above actually lives in
`superset-frontend/src/assets/images/tutorial`. Since the image is moved during
the documentation build process, the docs reference the image in
`_static/images/tutorial` instead.
+Commits to `master` trigger a rebuild and redeploy of the documentation site.
Submit pull requests that modify the documention with the `docs:` prefix.
### Flask server
@@ -1064,6 +1071,7 @@ LANGUAGES = {
```
This script will
+
1. update the template file `superset/translations/messages.pot` with current
application strings.
2. update language files with the new extracted strings.
diff --git a/docs/README.md b/docs/README.md
index f4a122ba2f..bd31f144c8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,36 +17,4 @@ 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 install
-```
-
-### 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.
+This is the public documentation site for Superset, built using [Docusaurus
2](https://docusaurus.io/). See
[CONTRIBUTING.md](../CONTRIBUTING.md#documentation)` for documentation on
contributing to documentation.
