From 7373e9c2561c582091ebfcad2fc7f755b1b2cf4a Mon Sep 17 00:00:00 2001 From: nikki everett Date: Fri, 13 Dec 2024 15:21:12 -0600 Subject: [PATCH 1/4] update README Signed-off-by: nikki everett --- docs/docs-beta/README.md | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/docs/docs-beta/README.md b/docs/docs-beta/README.md index 33e2e5fbf0ae8..2467c4c1db46c 100644 --- a/docs/docs-beta/README.md +++ b/docs/docs-beta/README.md @@ -3,7 +3,21 @@ This is the home of the new Dagster documentation. It is currently in beta and incomplete. The documentation site is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. ---- +## Overview of the docs + +- `./src` contains custom components, styles, themes, and layouts. +- `./content-templates` contains the templates for the documentation pages. +- `./docs/` is the source of truth for the documentation. +- `/examples/docs_beta_snippets/docs_beta_snippets/` contains all code examples for the documentation. + +The docs are broken down into the following sections: + +- Docs - includes content from [getting-started](./docs/getting-started/) and [guides](./docs/guides/) +- [Integrations](./docs/integrations/) +- [Dagster+](./docs/dagster-plus/) +- [API reference](./docs/api/) + +`sidebar.ts` and `docusaurus.config.ts` are the main configuration files for the documentation. ## Installation @@ -29,24 +43,6 @@ or pip install vale ``` ---- - -## Overview of the docs - -- `./src` contains custom components, styles, themes, and layouts. -- `./content-templates` contains the templates for the documentation pages. -- `./docs/` is the source of truth for the documentation. -- `/examples/docs_beta_snippets/docs_beta_snippets/` contains all code examples for the documentation. - -The docs are broken down into the following sections: - -- [Tutorials](./docs/tutorials/) -- [Guides](./docs/guides/) - -`sidebar.ts` and `docusaurus.config.ts` are the main configuration files for the documentation. - ---- - ## Local Development To start the local development server: From 09406bd73ed33d0977b81202c4570d698d24a683 Mon Sep 17 00:00:00 2001 From: nikki everett Date: Fri, 13 Dec 2024 15:37:32 -0600 Subject: [PATCH 2/4] refactor README and CONTRIBUTING Signed-off-by: nikki everett --- docs/docs-beta/CONTRIBUTING.md | 31 ++++++++++++++++++++++++++++++ docs/docs-beta/README.md | 35 ++-------------------------------- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/docs-beta/CONTRIBUTING.md b/docs/docs-beta/CONTRIBUTING.md index bddff1c929782..aae5219b8fe40 100644 --- a/docs/docs-beta/CONTRIBUTING.md +++ b/docs/docs-beta/CONTRIBUTING.md @@ -98,3 +98,34 @@ _There is not a replacement at this point in time..._ ### Whitespace via `{" "}` Forcing empty space using the `{" "}` interpolation is not supported, and must be removed. + +## Diagrams + +You can use [Mermaid.js](https://mermaid.js.org/syntax/flowchart.html) to create diagrams. For example: + +```mermaid +flowchart LR + Start --> Stop +``` + +Refer to the [Mermaid.js documentation](https://mermaid.js.org/) for more info. + +## Code examples + +To include code snippets, use the following format: + +``` + +``` + +The `filePath` is relative to the `./examples/docs_beta_snippets/docs_beta_snippets/` directory. + +At minimum, all `.py` files in the `docs_beta_snippets` directory are tested by attempting to load the Python files. +You can write additional tests for them in the `docs_beta_snippets_test` folder. See the folder for more information. + +To type-check the code snippets during development, run the following command from the Dagster root folder. +This will run `pyright` on all new/changed files relative to the master branch. + +``` +make quick_pyright +``` diff --git a/docs/docs-beta/README.md b/docs/docs-beta/README.md index 2467c4c1db46c..f93d16c691bb0 100644 --- a/docs/docs-beta/README.md +++ b/docs/docs-beta/README.md @@ -19,6 +19,8 @@ The docs are broken down into the following sections: `sidebar.ts` and `docusaurus.config.ts` are the main configuration files for the documentation. +For formatting guidelines, see the [CONTRIBUTING](CONTRIBUTING.md) guide. + ## Installation The site uses [yarn](https://yarnpkg.com/) for package management. @@ -68,39 +70,6 @@ yarn vale /path/to/file ## check individual file yarn vale --no-wrap ## remove wrapping from output ``` -### Diagrams - -You can use [Mermaid.js](https://mermaid.js.org/syntax/flowchart.html) to create diagrams. For example: - -```mermaid -flowchart LR - Start --> Stop -``` - -Refer to the [Mermaid.js documentation](https://mermaid.js.org/) for more info. - -### Code examples - -To include code snippets, use the following format: - -``` - -``` - -The `filePath` is relative to the `./examples/docs_beta_snippets/docs_beta_snippets/` directory. - -At minimum, all `.py` files in the `docs_beta_snippets` directory are tested by attempting to load the Python files. -You can write additional tests for them in the `docs_beta_snippets_test` folder. See the folder for more information. - -To type-check the code snippets during development, run the following command from the Dagster root folder. -This will run `pyright` on all new/changed files relative to the master branch. - -``` -make quick_pyright -``` - ---- - ## Build To build the site for production: From 518a8830e893eb9a476a9d00a5e6b48815d8bcdb Mon Sep 17 00:00:00 2001 From: nikki everett Date: Fri, 13 Dec 2024 15:41:25 -0600 Subject: [PATCH 3/4] re-add horizontal rules Signed-off-by: nikki everett --- docs/docs-beta/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/docs-beta/README.md b/docs/docs-beta/README.md index f93d16c691bb0..f07c8ddd61daa 100644 --- a/docs/docs-beta/README.md +++ b/docs/docs-beta/README.md @@ -3,6 +3,8 @@ This is the home of the new Dagster documentation. It is currently in beta and incomplete. The documentation site is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. +--- + ## Overview of the docs - `./src` contains custom components, styles, themes, and layouts. @@ -21,6 +23,8 @@ The docs are broken down into the following sections: For formatting guidelines, see the [CONTRIBUTING](CONTRIBUTING.md) guide. +--- + ## Installation The site uses [yarn](https://yarnpkg.com/) for package management. @@ -45,6 +49,8 @@ or pip install vale ``` +--- + ## Local Development To start the local development server: @@ -70,6 +76,8 @@ yarn vale /path/to/file ## check individual file yarn vale --no-wrap ## remove wrapping from output ``` +--- + ## Build To build the site for production: @@ -80,6 +88,8 @@ yarn build This command generates static content into the `build` directory and can be served using any static contents hosting service. This also checks for any broken links in the documentation. Note that you will need to store Algolia credentials in local environment variables to build the site for production. +--- + ## Deployment This site is built and deployed using Vercel. @@ -94,6 +104,8 @@ yarn sync-api-docs && yarn build This runs the `scripts/vercel-sync-api-docs.sh` script which builds the MDX files using the custom `sphinx-mdx-builder`, and copies the resulting MDX files to `docs/api/python-api`. +--- + ## Search Algolia search is used for search results on the website, as configured in `docusaurus.config.ts`. From 9ff83a4bd075d2d2370c45cb8a46173ea95b4e55 Mon Sep 17 00:00:00 2001 From: nikki everett Date: Fri, 13 Dec 2024 15:43:45 -0600 Subject: [PATCH 4/4] add horizontal rules Signed-off-by: nikki everett --- docs/docs-beta/CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docs-beta/CONTRIBUTING.md b/docs/docs-beta/CONTRIBUTING.md index aae5219b8fe40..f2b8d9d78c55b 100644 --- a/docs/docs-beta/CONTRIBUTING.md +++ b/docs/docs-beta/CONTRIBUTING.md @@ -99,6 +99,8 @@ _There is not a replacement at this point in time..._ Forcing empty space using the `{" "}` interpolation is not supported, and must be removed. +--- + ## Diagrams You can use [Mermaid.js](https://mermaid.js.org/syntax/flowchart.html) to create diagrams. For example: @@ -110,6 +112,8 @@ flowchart LR Refer to the [Mermaid.js documentation](https://mermaid.js.org/) for more info. +--- + ## Code examples To include code snippets, use the following format: