DOC-594 refactor new API docs (#26296)

## Summary & Motivation Copy API docs to /api/python-api instead of /api to give us space in the /api docs section for narrative docs. ## How I Tested These Changes Staging build -- I was unable to build API docs locally. ## Changelog > Insert changelog entry or delete this section. --------- Signed-off-by: nikki everett <[email protected]>
dagster-io · Dec 5, 2024 · 5425862 · 5425862 · github-actions · Dec 5, 2024
1 parent 5da96ff
commit 5425862
Show file tree

Hide file tree

Showing 10 changed files with 21 additions and 12 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -35,4 +35,4 @@ mdx:
 	tox -e sphinx-mdx
 
 mdx_copy:
-	cp -rf sphinx/_build/mdx/sections/api/apidocs/* docs-beta/docs/api/
+	cp -rf sphinx/_build/mdx/sections/api/apidocs/* docs-beta/docs/api/python-api/
diff --git a/docs/docs-beta/README.md b/docs/docs-beta/README.md
@@ -127,7 +127,7 @@ API documentation is built in Vercel by overriding the _Build Command_ to the fo
 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`.
+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
 

diff --git a/docs/docs-beta/docs/api/.gitignore b/docs/docs-beta/docs/api/.gitignore
diff --git a/docs/docs-beta/docs/api/.gitkeep b/docs/docs-beta/docs/api/.gitkeep
diff --git a/...docs-beta/docs/reference/api-lifecycle.md → docs/docs-beta/docs/api/api-lifecycle.md b/...docs-beta/docs/reference/api-lifecycle.md → docs/docs-beta/docs/api/api-lifecycle.md
diff --git a/docs/docs-beta/docs/api/index.mdx b/docs/docs-beta/docs/api/index.mdx
@@ -1,8 +1,7 @@
 ---
-sidebar_class_name: hidden
 title: API reference
 ---
 
-import DocCardList from '@theme/DocCardList';
+These docs aim to cover the entire public surface of the core dagster APIs, as well as public APIs from all provided libraries.
 
-<DocCardList />
+Dagster follows [semantic versioning](https://semver.org/). We attempt to isolate breaking changes to the public APIs to minor versions on a roughly 12-week cadence, and will announce deprecations in Slack and in the release notes to patch versions on a roughly weekly cadence.
diff --git a/docs/docs-beta/docs/api/python-api/.gitignore b/docs/docs-beta/docs/api/python-api/.gitignore
@@ -0,0 +1,2 @@
+**/*.mdx
+!index.mdx
diff --git a/docs/docs-beta/docs/api/python-api/index.mdx b/docs/docs-beta/docs/api/python-api/index.mdx
@@ -0,0 +1,8 @@
+---
+sidebar_class_name: hidden
+title: API reference
+---
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
diff --git a/docs/docs-beta/sidebars.ts b/docs/docs-beta/sidebars.ts
@@ -243,16 +243,17 @@ const sidebars: SidebarsConfig = {
     },
   ],
   api: [
-    'reference/api-lifecycle',
+    'api/index',
+    'api/api-lifecycle',
     {
       type: 'category',
       label: 'Python API',
       collapsed: false,
-      link: {type: 'doc', id: 'api/index'},
+      link: {type: 'doc', id: 'api/python-api/index'},
       items: [
         {
           type: 'autogenerated',
-          dirName: 'api',
+          dirName: 'api/python-api',
         },
       ],
     }

diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile
@@ -16,9 +16,9 @@ install:
 	uv pip install -e _ext/sphinx-mdx-builder
 
 mdx_copy:
-	rm -rf ../docs-beta/docs/api/libraries
-	find ../docs-beta/docs/api/*.mdx ! -name index.mdx -exec rm {} +
-	cp -rf _build/mdx/sections/api/apidocs/* ../docs-beta/docs/api/
+	rm -rf ../docs-beta/docs/api/python-api/libraries
+	find ../docs-beta/docs/api/python-api/*.mdx ! -name index.mdx -exec rm {} +
+	cp -rf _build/mdx/sections/api/apidocs/* ../docs-beta/docs/api/python-api/
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).