Replace Python SDK docs with vanilla Sphinx + Read the Docs theme (#1…

…0279)

This PR replaces our custom Sphinx-based tool for generating core Python SDK docs with standard docs generated from Sphinx using the Read the Docs theme.

.github/workflows/generate-provider-docs.yml

@@ -89,7 +89,7 @@ jobs:
         working-directory: docs
       - if: github.event.action == 'non-resource-provider'
         name: generate python docs
-        run: ./scripts/generate_python_docs.sh "${{ env.PROVIDER_SHORT_NAME }}"
+        run: ./scripts/generate_python_docs.sh
         working-directory: docs
       - name: git status
         if: github.event.action == 'non-resource-provider'

.github/workflows/pulumi-cli.yml

@@ -81,7 +81,7 @@ jobs:
         run: PKGS=pulumi NOBUILD=true ./scripts/run_typedoc.sh
         working-directory: docs
       - name: generate python docs
-        run: ./scripts/generate_python_docs.sh "pulumi"
+        run: ./scripts/generate_python_docs.sh
         working-directory: docs
       - name: generate markdown
         run: |

.gitignore

@@ -56,3 +56,6 @@ _vendor/
 
 # Ignore log files.
 /scripts/link-checker/pages-with-broken-links.txt
+
+.doctrees/
+.buildinfo

config/_default/menus.yml

@@ -220,7 +220,7 @@ languages:
   - name: SDK docs
     identifier: sdk-docs-python
     parent: python
-    pageRef: /docs/reference/pkg/python/pulumi
+    url: https://www.pulumi.com/docs/reference/pkg/python/pulumi/
     weight: 1
   - name: SDK docs
     identifier: sdk-docs-go

content/docs/reference/pkg/python/providers/pulumi/_index.md

@@ -0,0 +1,3 @@
+---
+redirect_to: /docs/reference/pkg/python/pulumi/
+---

content/docs/reference/pkg/python/providers/pulumi_policy/_index.md

@@ -0,0 +1,3 @@
+---
+redirect_to: /docs/reference/pkg/python/pulumi_policy/
+---

content/docs/reference/pkg/python/providers/pulumi_terraform/_index.md

@@ -0,0 +1,3 @@
+---
+redirect_to: /docs/reference/pkg/python/pulumi_terraform/
+---

content/docs/reference/pkg/python/providers/pulumi_terraform/state/_index.md

@@ -0,0 +1,3 @@
+---
+redirect_to: /docs/reference/pkg/python/pulumi_terraform/
+---

cypress/integration/site_spec.js

@@ -47,18 +47,4 @@ describe("www.pulumi.com", () => {
             });
         });
     });
-
-    describe("python SDK docs", () => {
-        beforeEach(() => {
-            cy.visit("/docs/reference/pkg/python/pulumi");
-        });
-
-        // Regression test for https://github.com/pulumi/docs/issues/1396, which has happened multiple times.
-        // The CSS is applied by targeting specific node structures due to the way our Python docs are generated.
-        it("is styled correctly", () => {
-            cy.get("#pulumi-python-sdk")
-                .invoke("css", "--pulumi-python-sdk")
-                .should("equal", "true");
-        });
-    });
 });

scripts/generate_python_docs.sh

@@ -3,40 +3,27 @@
 set -o errexit -o pipefail
 set -x
 
-# Optional argument to generate docs for just a single provider.
-REPO_OVERRIDE="${1:-}"
-
 PACKAGES=(
   "pulumi"
   "pulumi_policy"
   "pulumi_terraform"
 )
 
+OUTDIR="../../static-prebuilt/docs/reference/pkg/python"
+
 pushd "tools/pydocgen"
+
 pipenv --python 3
 pipenv install
-
 pipenv run pip install sphinx-rtd-theme
 
-if [ -z "${REPO_OVERRIDE:-}" ]; then
-    echo "Building all Python docs..."
-    # Install the Python package for all the providers.
-    for PACKAGE in "${PACKAGES[@]}" ; do \
-        pipenv run pip install "${PACKAGE}"
-    done
-
-    # Run the pydocgen to generate the docs for all the packages.
-    pipenv run python -m pydocgen "../../static-prebuilt/docs/reference/pkg/python" "../../content/docs/reference/pkg"
-else
-    # Install the Python package and run the pydocgen tool for just the provider that
-    # was requested.
-    echo "Building Python docs for ${REPO_OVERRIDE}..."
-    PACKAGE="pulumi"
-    if [ "${REPO_OVERRIDE}" != "pulumi" ]; then
-        PACKAGE="pulumi_${REPO_OVERRIDE}"
-    fi
+echo "Building all Python docs..."
+# Install each package.
+for PACKAGE in "${PACKAGES[@]}" ; do \
     pipenv run pip install "${PACKAGE}"
-    pipenv run python -m pydocgen "../../static-prebuilt/docs/reference/pkg/python" "../../content/docs/reference/pkg" "${PACKAGE}"
-fi
+done
+
+rm -rf "$OUTDIR"
+pipenv run sphinx-build -j auto -b dirhtml ./source "$OUTDIR"
 
 popd