(docs-infra-4/n) Render API docs

Summary: This diff renders the Sphinx API docs in the new site

Test Plan: bk

Reviewers: yuhan

Differential Revision: https://dagster.phacility.com/D6160

.buildkite/dagster-buildkite/dagster_buildkite/steps/docs.py

@@ -6,39 +6,12 @@
 
 def docs_steps() -> List[dict]:
     return [
-        # No docs tests for now
-        # StepBuilder("docs validate-libraries")
-        # .run("pip install -e python_modules/automation", "dagster-docs validate-libraries")
-        # .on_integration_image(SupportedPython.V3_7)
-        # .build(),
-        # StepBuilder("docs next build tests")
-        # .run(
-        #     "pip install -e python_modules/automation",
-        #     "pip install -r docs-requirements.txt -qqq",
-        #     "cd docs",
-        #     "make NODE_ENV=production VERSION=master full_docs_build",
-        # )
-        # .on_integration_image(SupportedPython.V3_7)
-        # .build(),
-        # StepBuilder("docs next tests")
-        # .run(
-        #     "pip install -e python_modules/automation",
-        #     "pip install -r docs-requirements.txt -qqq",
-        #     "cd docs",
-        #     "make buildnext",
-        #     "cd next",
-        #     "yarn test",
-        # )
-        # .on_integration_image(SupportedPython.V3_7)
-        # .build(),
-        # StepBuilder(":coverage: docs")
+        # TODO: Yuhan to fix
+        # StepBuilder("docs sphinx build")
         # .run(
-        #     "make install_dev_python_modules",
         #     "pip install -e python_modules/automation",
         #     "pip install -r docs-requirements.txt -qqq",
-        #     "cd docs",
-        #     "make updateindex",
-        #     "pytest -vv test_doc_build.py",
+        #     "pushd docs; make build",
         #     "git diff --exit-code",
         # )
         # .on_integration_image(SupportedPython.V3_7)

docs/Makefile

@@ -1,2 +1,2 @@
 build:
-	pushd sphinx; popd; python pack_json.py
+	cd sphinx; make clean; make json; cd ..; python pack_json.py

docs/next/package.json

@@ -21,7 +21,7 @@
   },
   "devDependencies": {
     "@types/classnames": "^2.2.11",
-    "@types/node": "^14.14.13",
+    "@types/node": "^14.14.22",
     "@types/react": "^17.0.0",
     "typescript": "^4.1.3"
   }

docs/next/pages/_apidocs/[...page].tsx

@@ -0,0 +1,55 @@
+import { promises as fs } from "fs";
+import path from "path";
+
+const ApiDocsPage = ({ body, data, page, curr }) => {
+  const markup = { __html: body };
+
+  return (
+    <div className="flex justify-center mt-10">
+      <div
+        className="prose prose-sm max-w-3xl"
+        dangerouslySetInnerHTML={markup}
+      />
+    </div>
+  );
+};
+
+const basePathForVersion = (version: string) => {
+  if (version === "master") {
+    return path.resolve("content");
+  }
+
+  return path.resolve(".versioned_content", version);
+};
+
+export async function getServerSideProps({ params, version = "master" }) {
+  const { page } = params;
+
+  const basePath = basePathForVersion(version);
+  const pathToFile = path.resolve(basePath, "api/sections.json");
+
+  try {
+    const buffer = await fs.readFile(pathToFile);
+    const {
+      api: { apidocs: data },
+    } = JSON.parse(buffer.toString());
+
+    let curr = data;
+    for (const part of page) {
+      curr = curr[part];
+    }
+
+    const { body } = curr;
+
+    return {
+      props: { body, data, page, curr },
+    };
+  } catch (err) {
+    console.log(err);
+    return {
+      notFound: true,
+    };
+  }
+}
+
+export default ApiDocsPage;

docs/next/pages/_apidocs/index.tsx

@@ -0,0 +1,9 @@
+const APIDocsIndex = () => {
+  return (
+    <div className="prose">
+      <h1>API Documentation Reference</h1>
+    </div>
+  );
+};
+
+export default APIDocsIndex;

docs/next/pages/_modules/[...page].tsx

@@ -0,0 +1,54 @@
+import { promises as fs } from "fs";
+import path from "path";
+
+const ApiDocsPage = ({ body, data, page, curr }) => {
+  const markup = { __html: body };
+
+  return (
+    <div className="flex justify-center mt-10">
+      <div
+        className="prose prose-sm max-w-none"
+        dangerouslySetInnerHTML={markup}
+      />
+    </div>
+  );
+};
+
+const basePathForVersion = (version: string) => {
+  if (version === "master") {
+    return path.resolve("content");
+  }
+
+  return path.resolve(".versioned_content", version);
+};
+
+export async function getServerSideProps({ params, version = "master" }) {
+  const { page } = params;
+
+  const basePath = basePathForVersion(version);
+  const pathToFile = path.resolve(basePath, "api/modules.json");
+
+  try {
+    const buffer = await fs.readFile(pathToFile);
+
+    const data = JSON.parse(buffer.toString());
+
+    let curr = data;
+    for (const part of page) {
+      curr = curr[part];
+    }
+
+    const { body } = curr;
+
+    return {
+      props: { body, data, page, curr },
+    };
+  } catch (err) {
+    console.log(err);
+    return {
+      notFound: true,
+    };
+  }
+}
+
+export default ApiDocsPage;

docs/next/pages/_modules/index.tsx

@@ -0,0 +1,9 @@
+const APIDocsIndex = () => {
+  return (
+    <div className="prose">
+      <h1>API Documentation Reference</h1>
+    </div>
+  );
+};
+
+export default APIDocsIndex;

docs/next/yarn.lock

@@ -175,7 +175,7 @@
   resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.7.tgz#98a993516c859eb0d5c4c8f098317a9ea68db9ad"
   integrity sha512-cxWFQVseBm6O9Gbw1IWb8r6OS4OhSt3hPZLkFApLjM8TEXROBuQGLAH2i2gZpcXdLBIrpXuTDhH7Vbm1iXmNGA==
 
-"@types/node@^14.14.13":
+"@types/node@^14.14.22":
   version "14.14.22"
   resolved "https://registry.yarnpkg.com/@types/node/-/node-14.14.22.tgz#0d29f382472c4ccf3bd96ff0ce47daf5b7b84b18"
   integrity sha512-g+f/qj/cNcqKkc3tFqlXOYjrmZA+jNBiDzbP3kH+B+otKFqAdPgVTGP1IeKRdMml/aE69as5S4FqtxAbl+LaMw==

docs/pack_json.py

@@ -48,9 +48,8 @@ def pack_directory_json(path_to_folder: str):
 
 
 def main():
-    # TODO: Update content directory to path in Next.js folder
     json_directory = file_relative_path(__file__, "sphinx/_build/json")
-    content_master_directory = file_relative_path(__file__, ".")
+    content_master_directory = file_relative_path(__file__, "next/content/api")
 
     directories_to_pack = {
         os.path.join(json_directory, "sections"): "sections.json",