asset apiref improvements (#8374)

dagster-io · Jun 14, 2022 · a20b02b · a20b02b · vercel · Jun 14, 2022
1 parent 42d4903
commit a20b02b
Show file tree

Hide file tree

Showing 7 changed files with 14 additions and 24 deletions.
diff --git a/docs/content/_apidocs.mdx b/docs/content/_apidocs.mdx
@@ -12,6 +12,8 @@ Dagster follows [SemVer](https://semver.org/). We attempt to isolate breaking ch
 
 APIs from the core `dagster` package, divided roughly by topic:
 
+- [Software-Defined Assets](/\_apidocs/assets). An asset is an object in persistent storage, such as a table, file, or persisted machine learning model. A software-defined asset is a Dagster object that couples an asset to the function and upstream assets that are used to produce its contents.
+
 - [Jobs](/\_apidocs/jobs) APIs to define jobs that execute a set of ops with specific parameters.
 
 - [Ops](/\_apidocs/ops) APIs to define or decorate functions as ops, declare their inputs and outputs, compose ops with each other, as well as the datatypes that op execution can return or yield.
@@ -46,8 +48,6 @@ APIs from the core `dagster` package, divided roughly by topic:
 
 - [Versioning & Memoization](/\_apidocs/memoization) (Experimental) Code versioning and memoization of previous outputs based upon that versioning.
 
-- [Software-Defined Assets](/\_apidocs/assets) (Experimental). Software-defined assets sit on top of the graph/job/op APIs and enable a novel way of constructing Dagster jobs that puts assets at the forefront.
-
 - [Utilities](/\_apidocs/utilities) Miscellaneous helpers used by Dagster that may be useful to users.
 
 - [Internals](/\_apidocs/internals) Core internal APIs that are important if you are interested in understanding how Dagster works with an eye towards extending it: logging, executors, system storage, the Dagster instance & plugin machinery, storage, schedulers.

diff --git a/docs/content/_navigation.json b/docs/content/_navigation.json
@@ -426,6 +426,10 @@
       {
         "title": "Core",
         "children": [
+          {
+            "title": "Software-Defined Assets",
+            "path": "/_apidocs/assets"
+          },
           {
             "title": "Jobs",
             "path": "/_apidocs/jobs"
@@ -494,10 +498,6 @@
             "title": "Versioning & Memoization",
             "path": "/_apidocs/memoization"
           },
-          {
-            "title": "Software-Defined Assets",
-            "path": "/_apidocs/assets"
-          },
           {
             "title": "Utilities",
             "path": "/_apidocs/utilities"

diff --git a/docs/content/api/modules.json b/docs/content/api/modules.json
diff --git a/docs/content/api/searchindex.json b/docs/content/api/searchindex.json
diff --git a/docs/content/api/sections.json b/docs/content/api/sections.json
diff --git a/docs/next/public/objects.inv b/docs/next/public/objects.inv
diff --git a/docs/sphinx/sections/api/apidocs/assets.rst b/docs/sphinx/sections/api/apidocs/assets.rst
@@ -1,30 +1,20 @@
 .. currentmodule:: dagster
 
-Software-Defined Assets (Experimental)
-======================================
+Software-Defined Assets
+=======================
 
-Software-defined assets sit on top of the graph/job/op APIs and enable a novel way of constructing Dagster jobs that puts assets at the forefront.
-
-Conceptually, software-defined assets invert the typical relationship between assets and computation. Instead of defining a graph of ops and recording which assets those ops end up materializing, you define a set of assets, each of which knows how to compute its contents from upstream assets.
-
-A software-defined asset combines:
-- An asset key, e.g. the name of a table.
-- A function, which can be run to compute the contents of the asset.
-- A set of upstream assets that are provided as inputs to the function when computing the asset.
+An asset is an object in persistent storage, such as a table, file, or persisted machine learning model. A software-defined asset is a Dagster object that couples an asset to the function and upstream assets that are used to produce its contents.
 
 .. autodecorator:: asset
 
-.. autoclass:: AssetGroup
-   :members:
-
 .. autodecorator:: multi_asset
 
-.. autofunction:: build_assets_job
-
 .. autoclass:: AssetIn
 
 .. autoclass:: SourceAsset
 
+.. autofunction:: define_asset_job
+
 .. autofunction:: load_assets_from_modules
 
 .. autofunction:: load_assets_from_current_module