Bridge Developer Docs (#2623)

Adds sphinx-based developer documentation to the bridge. Similar to pulumi/pulumi#16953 Can be previewed here: https://pulumi-terraform-bridge.readthedocs.io/en/latest/docs/README.html
pulumi · Nov 15, 2024 · e299594 · e299594
1 parent 2af31c4
commit e299594
Show file tree

Hide file tree

Showing 23 changed files with 358 additions and 6 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+#
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  commands:
+    - mkdir -p $READTHEDOCS_OUTPUT/html
+    - pip install -r docs/requirements.txt
+    - python -m sphinx -T -c docs/sphinx -b html -d _build/doctrees -D language=en . $READTHEDOCS_OUTPUT/html
+    - cp docs/sphinx/index.html.template $READTHEDOCS_OUTPUT/html/index.html
+
+sphinx:
+  configuration: docs/sphinx/conf.py
+
+formats:
+  - pdf
+
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/README.md b/README.md
@@ -51,6 +51,8 @@ behavior also leverages the Terraform provider schema, for operations like perfo
 
 This section only matters if you want to build this bridge from scratch, or use it in your own project.
 
+See also the Pulumi Terraform Bridge [developer docs](https://pulumi-developer-docs.readthedocs.io/projects/pulumi-terraform-bridge/en/latest/docs/README.html).
+
 ### Prerequisites
 
 Before doing any development, there are a few prerequisites to install:

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,3 @@
+.ensure.phony
+_build
+venv/
diff --git a/docs/.python-version b/docs/.python-version
@@ -0,0 +1 @@
+3.12
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,29 @@
+.PHONY: build watch
+
+ensure:: .ensure.phony
+.ensure.phony: requirements.txt
+	python -m venv venv
+	. venv/*/activate && python -m pip install --upgrade pip setuptools wheel
+	. venv/*/activate && python -m pip install -r requirements.txt
+	@touch .ensure.phony
+
+build: ensure
+	. venv/*/activate && sphinx-build \
+		-c sphinx \
+		-b html \
+		.. \
+		_build
+
+watch: ensure
+	. venv/*/activate && sphinx-autobuild \
+		-c sphinx \
+		-b html \
+		--ignore "*~" \
+		--ignore "*.swp" \
+		--ignore ".direnv/*" \
+		--ignore "*/.git/*" \
+		--ignore "*/.idea/*" \
+		--ignore "*/.direnv/*" \
+		--ignore "_build/*" \
+		.. \
+		_build
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,33 @@
+# Pulumi Terraform Bridge Developer Documentation
+
+Welcome to the Pulumi Terraform Bridge developer documentation! This site is designed to provide
+complete documentation for maintainers of and contributors to the Terraform Bridge as well as authors of Bridged Providers.
+
+Some topics of interest to provider maintainers might be:
+
+- {doc}`guides/new-provider`
+- {doc}`guides/muxwith`
+- {doc}`guides/upgrade-sdk-to-mux`
+- {doc}`guides/auto-aliasing`
+- {doc}`guides/automatic-token-mapping`
+- {doc}`guides/docs-edits`
+
+
+Some more advanced topics might be of interest to contributors:
+
+- {doc}`guides/testing`
+- {doc}`guides/sets`
+- {doc}`guides/metadata`
+
+
+Please refer to the main Pulumi {doc}`pulumi:docs/documentation` for information on how to work with the developer docs. The setup for the Pulumi Terraform Bridge developer docs is identical to the setup for the Pulumi developer docs.
+
+:::{toctree}
+:maxdepth: 2
+:titlesonly:
+
+self
+guides/README
+Pulumi Developer Documentation <https://pulumi-developer-docs.readthedocs.io/latest/docs/README.html>
+
+:::
diff --git a/docs/guides/README.md b/docs/guides/README.md
@@ -0,0 +1,19 @@
+# Guides
+
+:::{toctree}
+:maxdepth: 1
+:titlesonly:
+
+/docs/guides/auto-aliasing
+/docs/guides/autofill
+/docs/guides/automatic-token-mapping
+/docs/guides/docs-edits
+/docs/guides/metadata
+/docs/guides/muxwith
+/docs/guides/new-provider
+/docs/guides/overlays
+/docs/guides/resource-ids
+/docs/guides/sets
+/docs/guides/testing
+/docs/guides/upgrade-sdk-to-mux
+:::
diff --git a/docs/auto-aliasing.md → docs/guides/auto-aliasing.md b/docs/auto-aliasing.md → docs/guides/auto-aliasing.md
@@ -1,4 +1,6 @@
-# Automatic Aliasing (`ApplyAutoAliases`)
+# Automatic Aliasing
+
+## Automatic Aliasing (`ApplyAutoAliases`)
 
 Automatically applies backwards compatibility best practices.
 
@@ -51,7 +53,7 @@ from.
 
 The dataflow for aliases history goes like this:
 
-``` mermaid
+```mermaid
 flowchart TD
     A["Field History\n(bridge-metadata.json)"] -->|go:embed| B["resources.go: func Provider()"]
     B --> C["Token Mapping\n(manual & automatic)"]
@@ -110,7 +112,7 @@ For example, this is the (abbreviated & modified) history for GCP's compute auto
 
 Here are the details of each action as it applies to `"google_compute_autoscaler" in turn:
 
-# Call `ProviderInfo.RenameResourceWithAlias` or `ProviderInfo.RenameDataSource`
+## Call `ProviderInfo.RenameResourceWithAlias` or `ProviderInfo.RenameDataSource`
 
 "google_compute_autoscaler.majorVersion" tells us that this record was last updated at
 major version 6. One of the previous names is also at major version 6, so we want to
@@ -122,7 +124,7 @@ for the old Pulumi token
 hard aliased when `make tfgen` is run on version 7, since we are then allowed to make
 breaking changes.
 
-# Edit `ResourceInfo.Aliases`
+## Edit `ResourceInfo.Aliases`
 
 In this history, we have recorded two prior names for "google_compute_autoscaler":
 "gcp:auto/autoscalar:Autoscalar" and "gcp:auto/scaler:Scaler". Since
@@ -132,7 +134,7 @@ full backwards compatibility. Instead, we will apply a type alias to
 ""gcp:auto/scaler:Scaler"}`. This makes it easy for consumers to upgrade from the old
 name to the new.
 
-# Edit `SchemaInfo.MaxItemsOne`
+## Edit `SchemaInfo.MaxItemsOne`
 
 The provider has been shipped with fields that could have `MaxItemsOne` applied. Any
 change here is breaking to our users, so we prevent it. As long as the provider's major

diff --git a/docs/autofill.md → docs/guides/autofill.md b/docs/autofill.md → docs/guides/autofill.md
diff --git a/docs/automatic-token-mapping.md → docs/guides/automatic-token-mapping.md b/docs/automatic-token-mapping.md → docs/guides/automatic-token-mapping.md
diff --git a/docs/docs-edits.md → docs/guides/docs-edits.md b/docs/docs-edits.md → docs/guides/docs-edits.md
diff --git a/docs/metadata.md → docs/guides/metadata.md b/docs/metadata.md → docs/guides/metadata.md
diff --git a/docs/muxwith.md → docs/guides/muxwith.md b/docs/muxwith.md → docs/guides/muxwith.md
@@ -1,4 +1,6 @@
-# `tfbridge.ProviderInfo.MuxWith`
+# Muxing Providers
+
+## `tfbridge.ProviderInfo.MuxWith`
 
 [`tfbridge.ProviderInfo.MuxWith`](https://github.com/pulumi/pulumi-terraform-bridge/blob/5e17c6c7e2d877db7e1d9c0b953a06d3ecabbaea/pkg/tfbridge/info.go#L126-L133)
 allows the mixin (muxing) of other providers to the bridged upstream Terraform

diff --git a/docs/new-provider.md → docs/guides/new-provider.md b/docs/new-provider.md → docs/guides/new-provider.md
diff --git a/docs/overlays.md → docs/guides/overlays.md b/docs/overlays.md → docs/guides/overlays.md
diff --git a/docs/resource-ids.md → docs/guides/resource-ids.md b/docs/resource-ids.md → docs/guides/resource-ids.md
diff --git a/docs/sets.md → docs/guides/sets.md b/docs/sets.md → docs/guides/sets.md
diff --git a/docs/testing.md → docs/guides/testing.md b/docs/testing.md → docs/guides/testing.md
diff --git a/docs/upgrade-sdk-to-mux.md → docs/guides/upgrade-sdk-to-mux.md b/docs/upgrade-sdk-to-mux.md → docs/guides/upgrade-sdk-to-mux.md
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,48 @@
+accessible-pygments==0.0.5
+alabaster==0.7.16
+anyio==4.4.0
+Babel==2.15.0
+beautifulsoup4==4.12.3
+certifi==2024.7.4
+charset-normalizer==3.3.2
+click==8.1.7
+colorama==0.4.6
+commonmark==0.9.1
+docutils==0.20.1
+h11==0.14.0
+idna==3.7
+imagesize==1.4.1
+Jinja2==3.1.4
+markdown-it-py==3.0.0
+MarkupSafe==2.1.5
+mdit-py-plugins==0.4.1
+mdurl==0.1.2
+myst-parser==3.0.1
+packaging==24.1
+pydata-sphinx-theme==0.15.4
+Pygments==2.18.0
+PyYAML==6.0.1
+recommonmark==0.7.1
+requests==2.32.3
+sniffio==1.3.1
+snowballstemmer==2.2.0
+soupsieve==2.5
+Sphinx==7.4.7
+sphinx-autobuild==2024.4.16
+sphinx-book-theme==1.1.3
+sphinx-tabs==3.4.5
+sphinxcontrib-applehelp==1.0.8
+sphinxcontrib-devhelp==1.0.6
+sphinxcontrib-htmlhelp==2.0.6
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-mermaid==0.9.2
+sphinxcontrib-programoutput==0.17
+sphinxcontrib-qthelp==1.0.8
+sphinxcontrib-serializinghtml==1.1.10
+starlette==0.38.0
+typing_extensions==4.12.2
+urllib3==2.2.2
+uvicorn==0.30.3
+watchfiles==0.22.0
+websockets==12.0
diff --git a/docs/sphinx/_static/custom.css b/docs/sphinx/_static/custom.css
@@ -0,0 +1,4 @@
+.bd-container .bd-sidebar-primary div#rtd-footer-container {
+    margin-bottom: 0px;
+    margin-top: 0px;
+  }