[dg] Assorted docs fixes (BUILD-966) (#29184)

## Summary & Motivation

This PR is the result of a manual reading of all `dg`/components guides.
I was looking for:

- references to old project structure
- references to old APIs (e.g. `dg list component-type`, `dg init
--workspace-name`, ...)

I updated everything I could find. In a few cases the pages were so out
of date that I opened separate PRs for them:

- #29185
- #29181

## How I Tested These Changes

Existing test suite.

Author: smackesey

docs/docs/guides/labs/components/building-pipelines-with-components/creating-a-project-with-components.md

@@ -27,15 +27,14 @@ Running `dg scaffold project <project-name>` creates a fairly standard Python pr
 
 The following files and directories are included:
 
-- A Python package `jaffle_platform`-- the name is an underscored inflection of the
-  project root directory (`jaffle_platform`).
-- An (empty) `jaffle_platform_tests` test package.
+- A Python package `jaffle_platform` located in `src/jaffle_platform`-- the name is an underscored inflection of the project root directory (`jaffle-platform`).
+- An (empty) `tests` package.
 - A `uv.lock` file.
 - A `pyproject.toml` file.
 
 :::note
 
-For more information about the sections and settings in pyproject.toml, see "[pyproject.toml settings](/guides/labs/components/building-pipelines-with-components/pyproject-toml)".
+For more information about the sections and settings in `pyproject.toml`, see "[pyproject.toml settings](/guides/labs/components/building-pipelines-with-components/pyproject-toml)".
 
 :::
 

docs/docs/guides/labs/components/components-etl-pipeline-tutorial.md

@@ -62,7 +62,7 @@ To learn more about the files, directories, and default settings in a project sc
 
 ### 1. Add the Sling component type to your environment
 
-To ingest data, you must set up [Sling](https://slingdata.io/). However, if you list the available component types in your environment at this point, the Sling component won't appear, since the `dagster` package doesn't contain components for specific integrations (like Sling):
+To ingest data, you must set up [Sling](https://slingdata.io/). We can list the component types available to our project with `dg list plugins`. If we run this now, the Sling component won't appear, since the `dagster` package doesn't contain components for specific integrations (like Sling):
 
 <CliInvocationExample path="docs_snippets/docs_snippets/guides/components/index/7-dg-list-plugins.txt" />
 
@@ -72,15 +72,13 @@ To make the Sling component available in your environment, install the `dagster-
 
 :::note
 
-`dg` always operates in an isolated environment, but it is able to access the set of component types available in your project environment because it attempts to resolve a project root whenever it is run. If `dg` finds a `pyproject.toml` file with a `tool.dg.is_project = true` setting, then it will expect a `uv`-managed virtual environment to be present in the same directory. (This can be confirmed by the presence of a `uv.lock` file.)
-
-When you run commands like `dg list component-type` , `dg` obtains the results by identifying the in-scope project environment and querying it. In this case, the project environment was set up as part of the `dg scaffold project` command.
+When you run commands like `dg list plugins`, `dg` obtains the results by resolving a project environment and querying it. In this case, the project environment was set up as part of the `dg scaffold project` command. The `pyproject.toml` in newly scaffolded projects contains a setting `tool.dg.project.python_environment = "persistent_uv"`. This tells `dg` to expect a `uv`-managed virtual environment to be present in the project root directory. (This can be confirmed by the presence of a `uv.lock` file.)
 
 :::
 
 ### 2. Confirm availability of the Sling component type
 
-To confirm that the `dagster_sling.SlingReplicationCollectionComponent` component type is now available, run the `dg list component-type` command again:
+To confirm that the `dagster_sling.SlingReplicationCollectionComponent` component type is now available, run the `dg list plugins` command again:
 
 <CliInvocationExample path="docs_snippets/docs_snippets/guides/components/index/8-dg-list-plugins.txt" />
 
@@ -99,7 +97,7 @@ A single file, `component.yaml`, was created in the component folder. The `compo
 <CodeExample
   path="docs_snippets/docs_snippets/guides/components/index/11-component.yaml"
   language="YAML"
-  title="jaffle-platform/jaffle_platform/defs/ingest_files/component.yaml"
+  title="jaffle-platform/src/jaffle_platform/defs/ingest_files/component.yaml"
 />
 
 Right now the parameters define a single "replication"-- this is a Sling concept that specifies how data should be replicated from a source to a target. The details are specified in a `replication.yaml` file that is read by Sling. This file does not yet exist-- we are going to create it shortly.
@@ -121,15 +119,15 @@ Create a `replication.yaml` file that references the downloaded files:
 <CodeExample
   path="docs_snippets/docs_snippets/guides/components/index/13-replication.yaml"
   language="YAML"
-  title="jaffle-platform/jaffle_platform/defs/ingest_files/replication.yaml"
+  title="jaffle-platform/src/jaffle_platform/defs/ingest_files/replication.yaml"
 />
 
 Finally, modify the `component.yaml` file to tell the Sling component where replicated data with the `DUCKDB` target should be written:
 
 <CodeExample
   path="docs_snippets/docs_snippets/guides/components/index/14-component-connections.yaml"
   language="YAML"
-  title="jaffle-platform/jaffle_platform/defs/ingest_files/component.yaml"
+  title="jaffle-platform/src/jaffle_platform/defs/ingest_files/component.yaml"
 />
 
 ### 6. View and materialize assets in the Dagster UI
@@ -160,7 +158,7 @@ To interface with the dbt project, you will need to instantiate a Dagster dbt pr
 
 <CliInvocationExample contents="uv add dagster-dbt dbt-duckdb" />
 
-To confirm that the `dagster_dbt.DbtProjectComponent` component type is now available, run `dg list component-type`:
+To confirm that the `dagster_dbt.DbtProjectComponent` component type is now available, run `dg list plugins`:
 
 <CliInvocationExample path="docs_snippets/docs_snippets/guides/components/index/17-dg-list-plugins.txt" />
 
@@ -175,7 +173,7 @@ This creates a new component instance in the project at `jaffle_platform/defs/jd
 <CodeExample
   path="docs_snippets/docs_snippets/guides/components/index/19-component-jdbt.yaml"
   language="YAML"
-  title="jaffle-platform/jaffle_platform/defs/jdbt/component.yaml"
+  title="jaffle-platform/src/jaffle_platform/defs/jdbt/component.yaml"
 />
 
 ### 4. Update the dbt project component configuration
@@ -193,7 +191,7 @@ We need to update the configuration of the `dagster_dbt.DbtProjectComponent` com
 <CodeExample
   path="docs_snippets/docs_snippets/guides/components/index/20-project-jdbt-incorrect.yaml"
   language="YAML"
-  title="jaffle-platform/jaffle_platform/defs/jdbt/component.yaml"
+  title="jaffle-platform/src/jaffle_platform/defs/jdbt/component.yaml"
 />
 
 You might notice the typo in the above file--after updating a component file, it's useful to validate that the changes match the component's schema. You can do this by running `dg check yaml`:
@@ -205,7 +203,7 @@ You can see that the error message includes the filename, line number, and a cod
 <CodeExample
   path="docs_snippets/docs_snippets/guides/components/index/22-project-jdbt.yaml"
   language="YAML"
-  title="jaffle-platform/jaffle_platform/defs/jdbt/component.yaml"
+  title="jaffle-platform/src/jaffle_platform/defs/jdbt/component.yaml"
 />
 
 Finally, run `dg check yaml` again to validate the fix:
@@ -235,7 +233,7 @@ And now target `*` and schedule `@daily`:
 <CodeExample
   path="docs_snippets/docs_snippets/guides/components/index/26-daily-jaffle.py"
   language="Python"
-  title="jaffle-platform/jaffle_platform/defs/daily_jaffle.py"
+  title="jaffle-platform/src/jaffle_platform/defs/daily_jaffle.py"
 />
 
 ## Next steps

docs/docs/guides/labs/dg/configuring-dg.md

@@ -13,7 +13,7 @@ This guide covers using existing Dagster definitions with a `dg`-compatible proj
 
 :::
 
-In projects that heavily use `dg`, you would typically keep all definitions in the `defs/` directory. However, if you've converted an existing project to use `dg`, you may have definitions located in various other modules. This guide will show you how to move these existing definitions into the `defs` directory in a way that will allow them to be automatically loaded.
+In projects that are started with `dg`, all definitions are typically kept in the `defs/` directory. However, if you've converted an existing project to use `dg`, you may have definitions located in various other modules. This guide will show you how to move these existing definitions into the `defs` directory in a way that will allow them to be automatically loaded.
 
 ## Example project structure
 

docs/docs/guides/labs/dg/incrementally-adopting-dg/migrating-definitions.md

@@ -15,7 +15,7 @@ If you're just getting started, we recommend [scaffolding a single project](/gui
 
 If you need to collaborate with multiple teams, or work with conflicting dependencies that require isolation from each other, you can scaffold a workspace directory that contains multiple projects, each with their own separate Python environment.
 
-A workspace directory contains a root `pyproject.toml` with workspace-level settings, and a `projects` directory with one or more projects.
+A workspace directory contains a root `dg.toml` with workspace-level settings, and a `projects` directory with one or more projects.
 
 :::note
 
@@ -25,7 +25,7 @@ A workspace does not define a Python environment by default. Instead, Python env
 
 ## Scaffold a new workspace and first project
 
-To scaffold a new workspace with an initial project called `project-1`, run `dg init` with the `--workspace-name` option:
+To scaffold a new workspace with an initial project called `project-1`, run `dg init` with the `--workspace` option. You will be prompted for the name of the project:
 
 <CliInvocationExample path="docs_snippets/docs_snippets/guides/dg/workspace/1-dg-init.txt" />
 
@@ -37,12 +37,12 @@ The new workspace has the following structure:
 
 <CliInvocationExample path="docs_snippets/docs_snippets/guides/dg/workspace/2-tree.txt" />
 
-The `pyproject.toml` file for the `workspace` folder contains an `is_workspace` setting that marks this directory as a workspace:
+The `pyproject.toml` file for the `workspace` folder contains a `directory_type = "workspace"` setting that marks this directory as a workspace:
 
 <CodeExample
-  path="docs_snippets/docs_snippets/guides/dg/workspace/3-pyproject.toml"
+  path="docs_snippets/docs_snippets/guides/dg/workspace/3-dg.toml"
   language="TOML"
-  title="workspace/pyproject.toml"
+  title="dagster-workspace/dg.toml"
 />
 
 :::note
@@ -51,13 +51,13 @@ The `pyproject.toml` file for the `workspace` folder contains an `is_workspace`
 
 :::
 
-The `project-1` directory contains a `pyproject.toml` file that defines
-it as a Dagster project:
+The `project-1` directory contains a `pyproject.toml` file with a
+`tool.dg.directory_type = "project"` section that defines it as a `dg` project:
 
 <CodeExample
   path="docs_snippets/docs_snippets/guides/dg/workspace/4-project-pyproject.toml"
   language="TOML"
-  title="workspace/projects/project-1/pyproject.toml"
+  title="dagster-workspace/projects/project-1/pyproject.toml"
 />
 
 ## Add a second project to the workspace

docs/docs/guides/labs/dg/multiple-projects.md

@@ -19,15 +19,16 @@ The `dg init` command creates a directory with a standard Python package structu
 
 <CliInvocationExample path="docs_snippets/docs_snippets/guides/dg/scaffolding-project/2-tree.txt" />
 
-- The top-level package `my_project` contains the deployable code that defines
+- The Python package `my_project` lives in `src/my_project` and contains the deployable code that defines
   your Dagster pipelines.
 - `my_project/defs` will contain your Dagster definitions.
 - `my_project/lib` is where you will define custom component types, and
   optionally other code you wish to share across Dagster definitions.
 - `my_project/definitions.py` is the entry point that Dagster will load when
   deploying your code location. It is configured to load all definitions from
   `my_project/defs`. You should not need to modify this file.
-- `my_project_tests` contains tests for the code in `my_project`.
+- `tests` is a separate Python package defined at the top level (outside
+  `src`). It should contain tests for the `my_project` package.
 - `pyproject.toml` is a standard Python package configuration file. In addition
   to the regular Python package metadata, it contains a `tool.dg` section
   for `dg`-specific settings.