diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..a79ddd00f --- /dev/null +++ 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 \ No newline at end of file diff --git a/README.md b/README.md index 985fcd378..580420494 100644 --- 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 new file mode 100644 index 000000000..f87d23a9c --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +.ensure.phony +_build +venv/ \ No newline at end of file diff --git a/docs/.python-version b/docs/.python-version new file mode 100644 index 000000000..e4fba2183 --- /dev/null +++ b/docs/.python-version @@ -0,0 +1 @@ +3.12 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..8708c16c3 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..acf4cbc09 --- /dev/null +++ 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 + +::: \ No newline at end of file diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 000000000..240ef93fc --- /dev/null +++ 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 +::: \ No newline at end of file diff --git a/docs/auto-aliasing.md b/docs/guides/auto-aliasing.md similarity index 96% rename from docs/auto-aliasing.md rename to docs/guides/auto-aliasing.md index 3d062f6c9..8b8cd5dee 100644 --- a/docs/auto-aliasing.md +++ b/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 b/docs/guides/autofill.md similarity index 100% rename from docs/autofill.md rename to docs/guides/autofill.md diff --git a/docs/automatic-token-mapping.md b/docs/guides/automatic-token-mapping.md similarity index 100% rename from docs/automatic-token-mapping.md rename to docs/guides/automatic-token-mapping.md diff --git a/docs/docs-edits.md b/docs/guides/docs-edits.md similarity index 100% rename from docs/docs-edits.md rename to docs/guides/docs-edits.md diff --git a/docs/metadata.md b/docs/guides/metadata.md similarity index 100% rename from docs/metadata.md rename to docs/guides/metadata.md diff --git a/docs/muxwith.md b/docs/guides/muxwith.md similarity index 88% rename from docs/muxwith.md rename to docs/guides/muxwith.md index e13f2ccb6..2669b2977 100644 --- a/docs/muxwith.md +++ b/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 b/docs/guides/new-provider.md similarity index 100% rename from docs/new-provider.md rename to docs/guides/new-provider.md diff --git a/docs/overlays.md b/docs/guides/overlays.md similarity index 100% rename from docs/overlays.md rename to docs/guides/overlays.md diff --git a/docs/resource-ids.md b/docs/guides/resource-ids.md similarity index 100% rename from docs/resource-ids.md rename to docs/guides/resource-ids.md diff --git a/docs/sets.md b/docs/guides/sets.md similarity index 100% rename from docs/sets.md rename to docs/guides/sets.md diff --git a/docs/testing.md b/docs/guides/testing.md similarity index 100% rename from docs/testing.md rename to docs/guides/testing.md diff --git a/docs/upgrade-sdk-to-mux.md b/docs/guides/upgrade-sdk-to-mux.md similarity index 100% rename from docs/upgrade-sdk-to-mux.md rename to docs/guides/upgrade-sdk-to-mux.md diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..e6741b56a --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/sphinx/_static/custom.css b/docs/sphinx/_static/custom.css new file mode 100644 index 000000000..4a4bac939 --- /dev/null +++ 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; + } \ No newline at end of file diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py new file mode 100644 index 000000000..6b4799fa1 --- /dev/null +++ b/docs/sphinx/conf.py @@ -0,0 +1,174 @@ +from sphinx.ext.autodoc import between +import os +import sys +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +# -- Path setup -------------------------------------------------------------- +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.append(os.path.abspath("./_ext")) +# -- Project information ----------------------------------------------------- +project = "Pulumi Terraform Bridge" +copyright = "Pulumi 2024" +author = "Pulumi engineering" +# -- General configuration --------------------------------------------------- +# The master document, where the root table of contents ("toctree") lives. The +# extension is not needed here, so e.g. "README" corresponds to README.rst in +# the top-level directory. Our top-level README is designed to introduce Pulumi +# itself as a product, so we use the README in the "docs" directory as the +# master document (which is a Markdown file). +master_doc = "docs/README" +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named "sphinx.ext.*") or custom ones (which will likely +# come from the path extended above i.e. _ext). +extensions = [ + # Community extensions + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.autosectionlabel", + "sphinx.ext.intersphinx", + "sphinx_tabs.tabs", + "sphinxcontrib.mermaid", + "sphinxcontrib.programoutput", +] +# Extensions for MyST, which we use to support Markdown as an alternative to +# reStructuredText (Sphinx's default format). +myst_enable_extensions = [ + "attrs_inline", + "colon_fence", + "deflist", + "fieldlist", +] + +myst_links_external_new_tab = True + +# Languages listed here will be interpreted as directives when encountered after +# a code fence. For instance, if MyST sees the string "```mermaid", and mermaid +# is configured here, it will interpret it as if it had been written as a +# directive, e.g. "```{mermaid}". +# +# This is useful for interoperability with tools that have special support for +# certain languages. GitHub, for instance, will render Mermaid diagrams if it +# encounters them, so it's beneficial for us to be able to write them as +# "normal" code blocks rather than as directives. +myst_fence_as_directive = ["mermaid"] + +# Configure some custom MyST URL schemes for easy linking to GitHub files and +# issues. +myst_url_schemes = { + "http": None, + "https": None, + # Usage: + "gh-file": { + "url": "https://github.com/pulumi/{{path}}/blob/master/{{fragment}}", + "title": "pulumi/{{path}}:{{fragment}}", + "classes": ["github"], + }, + # Usage: + "gh-issue": { + "url": "https://github.com/pulumi/{{path}}/issues/{{fragment}}", + "title": "pulumi/{{path}} #{{fragment}}", + "classes": ["github"], + }, +} + +# Intersphinx enables linking to references and the like in other Sphinx +# documentation sites. We configure it here so that we can link to the various +# Pulumi projects that are all hosted under the root Pulumi site. +intersphinx_mapping = { + # Pulumi developer documentation + "pulumi": ("https://pulumi-developer-docs.readthedocs.io/latest/", None), +} + +# Sphinx defaults to trying to automatically resolve *unresolved* labels using +# Intersphinx mappings. This can have unintended side effects, such as local +# references suddenly resolving to external locations. As a result we disable +# this behaviour here. See +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes +# for more information. +intersphinx_disabled_reftypes = ["*"] + +# The types of source files and suffixes that Sphinx should recognise and parse. +source_suffix = { + ".md": "markdown", + ".rst": "restructuredtext", +} +# Configuration for the "autosectionlabel" extension, which generates references +# to section headers automatically (and is thus super user for Markdown files +# where explicitly writing such references can sometimes be tedious). +autosectionlabel_prefix_document = True +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] +# A list of of patterns, relative to the source directory, that match files and +# directories to ignore when looking for source files. These patterns also +# affect html_static_path and html_extra_path. +exclude_patterns = [ + # General noise + "**/*.rst.inc", + "**/node_modules", + "**/site-packages", + ".direnv", + ".git", + "node_modules", + # Pulumi-specific cases + ## Standalone documentation files/noise from vendored libraries (CHANGELOGs, + ## LICENSEs, etc.) + "CHANGELOG.md", + "CODE_OF_CONDUCT.md", + "CONTRIBUTING.md", + "README.md", + ## Test data + "**/testdata", +] +# -- Options for HTML output ------------------------------------------------- +# The theme to use for HTML and HTML Help pages. We are using the "book" theme +# from the sphinx_book_theme package. See +# https://sphinx-book-theme.readthedocs.io/ for more information on the theme +# and its options. +# +html_theme = "sphinx_book_theme" +html_title = "Pulumi Terraform Bridge Developer Documentation" +html_logo = "https://www.pulumi.com/images/logo/logo-on-white-box.svg" +html_theme_options = { + # Expand all headings up to level 2 by default in the left sidebar (global) + # table of contents. + "show_navbar_depth": 2, + # Show all headings up to level 2 in the right sidebar (in-page) table of + # contents. + "show_toc_level": 2, + # Expand all headings up to level 2 by default in the sidebar table of + # contents. + # Enable margin notes + # (https://sphinx-book-theme.readthedocs.io/en/stable/content/content-blocks.html#sidenotes-and-marginnotes). + "use_sidenotes": True, + # Enable linking to GitHub page sources and editing files directly in the + # browser. + "repository_provider": "github", + "repository_url": "https://github.com/pulumi/pulumi-terraform-bridge", + "repository_branch": "master", + "use_source_button": True, + "use_edit_page_button": True, + "use_issues_button": True, +} +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, so +# a file named "default.css" will overwrite the builtin "default.css". Note +# that, annoyingly, making changes to these files requires a full rebuild of the +# documentation (that is, the default incremental build won't pick up changes to +# these files). +html_static_path = ["_static"] +html_css_files = ["custom.css"] +# -- Application-specific setup ---------------------------------------------- +def setup(app): + # Connect a listener which ignores any text between ".. AUTODOC-IGNORE" + # markers when autodoc is processing docstrings. This means that, for + # example, custom roles and directives can include documentation that talks + # both about the role API as well as how it should be consumed. + app.connect( + "autodoc-process-docstring", between("^.*\.\. AUTODOC-IGNORE.*$", exclude=True) + ) + return app \ No newline at end of file diff --git a/docs/sphinx/index.html.template b/docs/sphinx/index.html.template new file mode 100644 index 000000000..473107497 --- /dev/null +++ b/docs/sphinx/index.html.template @@ -0,0 +1,10 @@ + + + + Pulumi Terraform Bridge developer documentation + + + + + + \ No newline at end of file