diff --git a/.gitignore b/.gitignore index e4dd404b..bfeb9d89 100644 --- a/.gitignore +++ b/.gitignore @@ -138,3 +138,10 @@ protos.bin # Local RSA keys .local/* +# Sphinx docs build output +docs/build/ + +# autosummary generated stubs +docs/source/api/models_generated/ +docs/source/api/resources_generated/ + diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..59572932 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,26 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version, and other tools you might need +build: + os: ubuntu-24.04 + tools: + python: "3.13" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/source/conf.py + +# Optionally, but recommended, +# declare the Python requirements required to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt + - method: pip + path: . + extra_requirements: + - docs \ No newline at end of file diff --git a/Makefile b/Makefile index 8eb56545..6dd12d24 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help fmt fmt-check lint check test install dev-install type-check clean all venv activate +.PHONY: help fmt fmt-check lint check test install dev-install type-check clean all venv activate docs-install docs docs-clean docs-linkcheck PYTHON := python3 SRC_DIR := src/pytfe @@ -6,6 +6,7 @@ TEST_DIR := tests VENV := .venv VENV_PYTHON := $(VENV)/bin/python VENV_PIP := $(VENV)/bin/pip +DOCS_DIR := docs help: @echo "Available targets:" @@ -69,5 +70,21 @@ clean: find . -type d -name ".mypy_cache" -exec rm -rf {} + find . -type d -name ".ruff_cache" -exec rm -rf {} + rm -rf build/ dist/ $(VENV) + rm -rf $(DOCS_DIR)/build + + +# Documentation +docs-install: venv + $(VENV_PIP) install -e ".[docs]" + +docs: venv + $(VENV_PYTHON) -m sphinx -b html $(DOCS_DIR)/source $(DOCS_DIR)/build/html + @echo "Docs built: open $(DOCS_DIR)/build/html/index.html" + +docs-clean: + rm -rf $(DOCS_DIR)/build + +docs-linkcheck: venv + $(VENV_PYTHON) -m sphinx -b linkcheck $(DOCS_DIR)/source $(DOCS_DIR)/build/linkcheck all: clean dev-install fmt lint test diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..dc102d60 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx>=7.0,<9.0 +sphinx-autodoc-typehints>=2.0 +sphinx-rtd-theme>=3.0 +myst-parser>=3.0 \ No newline at end of file diff --git a/docs/source/api/client.rst b/docs/source/api/client.rst new file mode 100644 index 00000000..f05270e5 --- /dev/null +++ b/docs/source/api/client.rst @@ -0,0 +1,5 @@ +Client +====== +.. automodule:: pytfe.client + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/api/config.rst b/docs/source/api/config.rst new file mode 100644 index 00000000..4ccae9aa --- /dev/null +++ b/docs/source/api/config.rst @@ -0,0 +1,5 @@ +Configuration +============= +.. automodule:: pytfe.config + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/api/errors.rst b/docs/source/api/errors.rst new file mode 100644 index 00000000..4d2568e2 --- /dev/null +++ b/docs/source/api/errors.rst @@ -0,0 +1,5 @@ +Errors +====== +.. automodule:: pytfe.errors + :members: + :show-inheritance: \ No newline at end of file diff --git a/docs/source/api/models.rst b/docs/source/api/models.rst new file mode 100644 index 00000000..eeed65fd --- /dev/null +++ b/docs/source/api/models.rst @@ -0,0 +1,53 @@ +Models +====== + +This section documents all Pydantic data models in the ``pytfe.models`` package. +These models represent API request/response objects and are used as inputs and +outputs by the resource classes. + +.. toctree:: + :maxdepth: 1 + + models/agent + models/apply + models/comment + models/common + models/configuration_version + models/cost_estimate + models/data_retention_policy + models/notification_configuration + models/oauth_client + models/oauth_token + models/organization + models/organization_membership + models/plan + models/plan_export + models/policy + models/policy_check + models/policy_evaluation + models/policy_set + models/policy_set_outcome + models/policy_set_parameter + models/policy_set_version + models/policy_types + models/project + models/query_run + models/registry_module + models/registry_provider + models/registry_provider_version + models/reserved_tag_key + models/run + models/run_event + models/run_task + models/run_trigger + models/ssh_key + models/state_version + models/state_version_output + models/task_stage + models/team + models/user + models/variable + models/variable_set + models/workspace + models/workspace_resource + models/workspace_run_task \ No newline at end of file diff --git a/docs/source/api/models/agent.rst b/docs/source/api/models/agent.rst new file mode 100644 index 00000000..b82e1a5c --- /dev/null +++ b/docs/source/api/models/agent.rst @@ -0,0 +1,8 @@ +Agent & Agent Pool Models +========================= + +.. automodule:: pytfe.models.agent + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/apply.rst b/docs/source/api/models/apply.rst new file mode 100644 index 00000000..0cc295ad --- /dev/null +++ b/docs/source/api/models/apply.rst @@ -0,0 +1,8 @@ +Apply Models +============ + +.. automodule:: pytfe.models.apply + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/comment.rst b/docs/source/api/models/comment.rst new file mode 100644 index 00000000..d65a5b83 --- /dev/null +++ b/docs/source/api/models/comment.rst @@ -0,0 +1,8 @@ +Comment Models +============== + +.. automodule:: pytfe.models.comment + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/common.rst b/docs/source/api/models/common.rst new file mode 100644 index 00000000..2ce799b0 --- /dev/null +++ b/docs/source/api/models/common.rst @@ -0,0 +1,8 @@ +Common Models +============= + +.. automodule:: pytfe.models.common + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/configuration_version.rst b/docs/source/api/models/configuration_version.rst new file mode 100644 index 00000000..669b5e77 --- /dev/null +++ b/docs/source/api/models/configuration_version.rst @@ -0,0 +1,8 @@ +Configuration Version Models +============================ + +.. automodule:: pytfe.models.configuration_version + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/cost_estimate.rst b/docs/source/api/models/cost_estimate.rst new file mode 100644 index 00000000..1a0b9a8e --- /dev/null +++ b/docs/source/api/models/cost_estimate.rst @@ -0,0 +1,8 @@ +Cost Estimate Models +==================== + +.. automodule:: pytfe.models.cost_estimate + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/data_retention_policy.rst b/docs/source/api/models/data_retention_policy.rst new file mode 100644 index 00000000..1120d183 --- /dev/null +++ b/docs/source/api/models/data_retention_policy.rst @@ -0,0 +1,8 @@ +Data Retention Policy Models +============================ + +.. automodule:: pytfe.models.data_retention_policy + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/notification_configuration.rst b/docs/source/api/models/notification_configuration.rst new file mode 100644 index 00000000..ca7702d7 --- /dev/null +++ b/docs/source/api/models/notification_configuration.rst @@ -0,0 +1,8 @@ +Notification Configuration Models +================================= + +.. automodule:: pytfe.models.notification_configuration + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/oauth_client.rst b/docs/source/api/models/oauth_client.rst new file mode 100644 index 00000000..e4d6206c --- /dev/null +++ b/docs/source/api/models/oauth_client.rst @@ -0,0 +1,8 @@ +OAuth Client Models +=================== + +.. automodule:: pytfe.models.oauth_client + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/oauth_token.rst b/docs/source/api/models/oauth_token.rst new file mode 100644 index 00000000..2c452bad --- /dev/null +++ b/docs/source/api/models/oauth_token.rst @@ -0,0 +1,8 @@ +OAuth Token Models +================== + +.. automodule:: pytfe.models.oauth_token + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/organization.rst b/docs/source/api/models/organization.rst new file mode 100644 index 00000000..7f75952d --- /dev/null +++ b/docs/source/api/models/organization.rst @@ -0,0 +1,8 @@ +Organization Models +=================== + +.. automodule:: pytfe.models.organization + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/organization_membership.rst b/docs/source/api/models/organization_membership.rst new file mode 100644 index 00000000..18e3e1c4 --- /dev/null +++ b/docs/source/api/models/organization_membership.rst @@ -0,0 +1,8 @@ +Organization Membership Models +============================== + +.. automodule:: pytfe.models.organization_membership + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/plan.rst b/docs/source/api/models/plan.rst new file mode 100644 index 00000000..ab639452 --- /dev/null +++ b/docs/source/api/models/plan.rst @@ -0,0 +1,8 @@ +Plan Models +=========== + +.. automodule:: pytfe.models.plan + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/plan_export.rst b/docs/source/api/models/plan_export.rst new file mode 100644 index 00000000..3e6717d3 --- /dev/null +++ b/docs/source/api/models/plan_export.rst @@ -0,0 +1,8 @@ +Plan Export Models +================== + +.. automodule:: pytfe.models.plan_export + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/policy.rst b/docs/source/api/models/policy.rst new file mode 100644 index 00000000..b699de50 --- /dev/null +++ b/docs/source/api/models/policy.rst @@ -0,0 +1,8 @@ +Policy Models +============= + +.. automodule:: pytfe.models.policy + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/policy_check.rst b/docs/source/api/models/policy_check.rst new file mode 100644 index 00000000..114795be --- /dev/null +++ b/docs/source/api/models/policy_check.rst @@ -0,0 +1,8 @@ +Policy Check Models +=================== + +.. automodule:: pytfe.models.policy_check + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/policy_evaluation.rst b/docs/source/api/models/policy_evaluation.rst new file mode 100644 index 00000000..1a658159 --- /dev/null +++ b/docs/source/api/models/policy_evaluation.rst @@ -0,0 +1,8 @@ +Policy Evaluation Models +======================== + +.. automodule:: pytfe.models.policy_evaluation + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/policy_set.rst b/docs/source/api/models/policy_set.rst new file mode 100644 index 00000000..f8f66865 --- /dev/null +++ b/docs/source/api/models/policy_set.rst @@ -0,0 +1,8 @@ +Policy Set Models +================= + +.. automodule:: pytfe.models.policy_set + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/policy_set_outcome.rst b/docs/source/api/models/policy_set_outcome.rst new file mode 100644 index 00000000..1cb2a5b2 --- /dev/null +++ b/docs/source/api/models/policy_set_outcome.rst @@ -0,0 +1,8 @@ +Policy Set Outcome Models +========================= + +.. automodule:: pytfe.models.policy_set_outcome + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/policy_set_parameter.rst b/docs/source/api/models/policy_set_parameter.rst new file mode 100644 index 00000000..cad794d2 --- /dev/null +++ b/docs/source/api/models/policy_set_parameter.rst @@ -0,0 +1,8 @@ +Policy Set Parameter Models +=========================== + +.. automodule:: pytfe.models.policy_set_parameter + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/policy_set_version.rst b/docs/source/api/models/policy_set_version.rst new file mode 100644 index 00000000..fd2d1649 --- /dev/null +++ b/docs/source/api/models/policy_set_version.rst @@ -0,0 +1,8 @@ +Policy Set Version Models +========================= + +.. automodule:: pytfe.models.policy_set_version + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/policy_types.rst b/docs/source/api/models/policy_types.rst new file mode 100644 index 00000000..2ebf56e2 --- /dev/null +++ b/docs/source/api/models/policy_types.rst @@ -0,0 +1,8 @@ +Policy Type Models +================== + +.. automodule:: pytfe.models.policy_types + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/project.rst b/docs/source/api/models/project.rst new file mode 100644 index 00000000..45d97ec5 --- /dev/null +++ b/docs/source/api/models/project.rst @@ -0,0 +1,8 @@ +Project Models +============== + +.. automodule:: pytfe.models.project + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/query_run.rst b/docs/source/api/models/query_run.rst new file mode 100644 index 00000000..3ad96ef5 --- /dev/null +++ b/docs/source/api/models/query_run.rst @@ -0,0 +1,8 @@ +Query Run Models +================ + +.. automodule:: pytfe.models.query_run + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/registry_module.rst b/docs/source/api/models/registry_module.rst new file mode 100644 index 00000000..1951159f --- /dev/null +++ b/docs/source/api/models/registry_module.rst @@ -0,0 +1,8 @@ +Registry Module Models +====================== + +.. automodule:: pytfe.models.registry_module + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/registry_provider.rst b/docs/source/api/models/registry_provider.rst new file mode 100644 index 00000000..ca30596e --- /dev/null +++ b/docs/source/api/models/registry_provider.rst @@ -0,0 +1,8 @@ +Registry Provider Models +======================== + +.. automodule:: pytfe.models.registry_provider + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/registry_provider_version.rst b/docs/source/api/models/registry_provider_version.rst new file mode 100644 index 00000000..027633d6 --- /dev/null +++ b/docs/source/api/models/registry_provider_version.rst @@ -0,0 +1,8 @@ +Registry Provider Version Models +================================ + +.. automodule:: pytfe.models.registry_provider_version + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/reserved_tag_key.rst b/docs/source/api/models/reserved_tag_key.rst new file mode 100644 index 00000000..6e5957b8 --- /dev/null +++ b/docs/source/api/models/reserved_tag_key.rst @@ -0,0 +1,8 @@ +Reserved Tag Key Models +======================= + +.. automodule:: pytfe.models.reserved_tag_key + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/run.rst b/docs/source/api/models/run.rst new file mode 100644 index 00000000..448eba4c --- /dev/null +++ b/docs/source/api/models/run.rst @@ -0,0 +1,8 @@ +Run Models +========== + +.. automodule:: pytfe.models.run + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/run_event.rst b/docs/source/api/models/run_event.rst new file mode 100644 index 00000000..9621af45 --- /dev/null +++ b/docs/source/api/models/run_event.rst @@ -0,0 +1,8 @@ +Run Event Models +================ + +.. automodule:: pytfe.models.run_event + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/run_task.rst b/docs/source/api/models/run_task.rst new file mode 100644 index 00000000..17a0bbbd --- /dev/null +++ b/docs/source/api/models/run_task.rst @@ -0,0 +1,8 @@ +Run Task Models +=============== + +.. automodule:: pytfe.models.run_task + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/run_trigger.rst b/docs/source/api/models/run_trigger.rst new file mode 100644 index 00000000..14aec856 --- /dev/null +++ b/docs/source/api/models/run_trigger.rst @@ -0,0 +1,8 @@ +Run Trigger Models +================== + +.. automodule:: pytfe.models.run_trigger + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/ssh_key.rst b/docs/source/api/models/ssh_key.rst new file mode 100644 index 00000000..f991d559 --- /dev/null +++ b/docs/source/api/models/ssh_key.rst @@ -0,0 +1,8 @@ +SSH Key Models +============== + +.. automodule:: pytfe.models.ssh_key + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/state_version.rst b/docs/source/api/models/state_version.rst new file mode 100644 index 00000000..97efd349 --- /dev/null +++ b/docs/source/api/models/state_version.rst @@ -0,0 +1,8 @@ +State Version Models +==================== + +.. automodule:: pytfe.models.state_version + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/state_version_output.rst b/docs/source/api/models/state_version_output.rst new file mode 100644 index 00000000..ff30e766 --- /dev/null +++ b/docs/source/api/models/state_version_output.rst @@ -0,0 +1,8 @@ +State Version Output Models +=========================== + +.. automodule:: pytfe.models.state_version_output + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/task_stage.rst b/docs/source/api/models/task_stage.rst new file mode 100644 index 00000000..ba291912 --- /dev/null +++ b/docs/source/api/models/task_stage.rst @@ -0,0 +1,8 @@ +Task Stage Models +================= + +.. automodule:: pytfe.models.task_stage + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/team.rst b/docs/source/api/models/team.rst new file mode 100644 index 00000000..45dd2f4f --- /dev/null +++ b/docs/source/api/models/team.rst @@ -0,0 +1,8 @@ +Team Models +=========== + +.. automodule:: pytfe.models.team + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/user.rst b/docs/source/api/models/user.rst new file mode 100644 index 00000000..da54000e --- /dev/null +++ b/docs/source/api/models/user.rst @@ -0,0 +1,8 @@ +User Models +=========== + +.. automodule:: pytfe.models.user + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/variable.rst b/docs/source/api/models/variable.rst new file mode 100644 index 00000000..2520baf2 --- /dev/null +++ b/docs/source/api/models/variable.rst @@ -0,0 +1,8 @@ +Variable Models +=============== + +.. automodule:: pytfe.models.variable + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/variable_set.rst b/docs/source/api/models/variable_set.rst new file mode 100644 index 00000000..db4c167d --- /dev/null +++ b/docs/source/api/models/variable_set.rst @@ -0,0 +1,8 @@ +Variable Set Models +=================== + +.. automodule:: pytfe.models.variable_set + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/workspace.rst b/docs/source/api/models/workspace.rst new file mode 100644 index 00000000..7b193a57 --- /dev/null +++ b/docs/source/api/models/workspace.rst @@ -0,0 +1,8 @@ +Workspace Models +================ + +.. automodule:: pytfe.models.workspace + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/workspace_resource.rst b/docs/source/api/models/workspace_resource.rst new file mode 100644 index 00000000..a3164b85 --- /dev/null +++ b/docs/source/api/models/workspace_resource.rst @@ -0,0 +1,8 @@ +Workspace Resource Models +========================= + +.. automodule:: pytfe.models.workspace_resource + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/models/workspace_run_task.rst b/docs/source/api/models/workspace_run_task.rst new file mode 100644 index 00000000..c15e29c2 --- /dev/null +++ b/docs/source/api/models/workspace_run_task.rst @@ -0,0 +1,8 @@ +Workspace Run Task Models +========================= + +.. automodule:: pytfe.models.workspace_run_task + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources.rst b/docs/source/api/resources.rst new file mode 100644 index 00000000..ed167649 --- /dev/null +++ b/docs/source/api/resources.rst @@ -0,0 +1,44 @@ +Resources +========= + +This section documents all resource classes in the ``pytfe.resources`` package. +Each resource provides CRUD operations and other API methods for a specific +HCP Terraform / Terraform Enterprise resource type. + +.. toctree:: + :maxdepth: 1 + + resources/agent_pools + resources/agents + resources/apply + resources/configuration_version + resources/notification_configuration + resources/oauth_client + resources/oauth_token + resources/organization_membership + resources/organizations + resources/plan + resources/policy + resources/policy_check + resources/policy_evaluation + resources/policy_set + resources/policy_set_outcome + resources/policy_set_parameter + resources/policy_set_version + resources/projects + resources/query_run + resources/registry_module + resources/registry_provider + resources/registry_provider_version + resources/reserved_tag_key + resources/run + resources/run_event + resources/run_task + resources/run_trigger + resources/ssh_keys + resources/state_version_outputs + resources/state_versions + resources/variable + resources/variable_sets + resources/workspace_resources + resources/workspaces \ No newline at end of file diff --git a/docs/source/api/resources/agent_pools.rst b/docs/source/api/resources/agent_pools.rst new file mode 100644 index 00000000..255c4bab --- /dev/null +++ b/docs/source/api/resources/agent_pools.rst @@ -0,0 +1,8 @@ +Agent Pools +=========== + +.. automodule:: pytfe.resources.agent_pools + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/agents.rst b/docs/source/api/resources/agents.rst new file mode 100644 index 00000000..54fde5b6 --- /dev/null +++ b/docs/source/api/resources/agents.rst @@ -0,0 +1,8 @@ +Agents +====== + +.. automodule:: pytfe.resources.agents + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/apply.rst b/docs/source/api/resources/apply.rst new file mode 100644 index 00000000..08d0a3c8 --- /dev/null +++ b/docs/source/api/resources/apply.rst @@ -0,0 +1,8 @@ +Apply +===== + +.. automodule:: pytfe.resources.apply + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/configuration_version.rst b/docs/source/api/resources/configuration_version.rst new file mode 100644 index 00000000..64f41b4d --- /dev/null +++ b/docs/source/api/resources/configuration_version.rst @@ -0,0 +1,8 @@ +Configuration Versions +====================== + +.. automodule:: pytfe.resources.configuration_version + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/notification_configuration.rst b/docs/source/api/resources/notification_configuration.rst new file mode 100644 index 00000000..a77bf222 --- /dev/null +++ b/docs/source/api/resources/notification_configuration.rst @@ -0,0 +1,8 @@ +Notification Configurations +=========================== + +.. automodule:: pytfe.resources.notification_configuration + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/oauth_client.rst b/docs/source/api/resources/oauth_client.rst new file mode 100644 index 00000000..3a1c7310 --- /dev/null +++ b/docs/source/api/resources/oauth_client.rst @@ -0,0 +1,8 @@ +OAuth Clients +============= + +.. automodule:: pytfe.resources.oauth_client + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/oauth_token.rst b/docs/source/api/resources/oauth_token.rst new file mode 100644 index 00000000..8257c694 --- /dev/null +++ b/docs/source/api/resources/oauth_token.rst @@ -0,0 +1,8 @@ +OAuth Tokens +============ + +.. automodule:: pytfe.resources.oauth_token + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/organization_membership.rst b/docs/source/api/resources/organization_membership.rst new file mode 100644 index 00000000..e397558e --- /dev/null +++ b/docs/source/api/resources/organization_membership.rst @@ -0,0 +1,8 @@ +Organization Memberships +======================== + +.. automodule:: pytfe.resources.organization_membership + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/organizations.rst b/docs/source/api/resources/organizations.rst new file mode 100644 index 00000000..38747cb7 --- /dev/null +++ b/docs/source/api/resources/organizations.rst @@ -0,0 +1,8 @@ +Organizations +============= + +.. automodule:: pytfe.resources.organizations + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/plan.rst b/docs/source/api/resources/plan.rst new file mode 100644 index 00000000..5d61b2ab --- /dev/null +++ b/docs/source/api/resources/plan.rst @@ -0,0 +1,8 @@ +Plans +===== + +.. automodule:: pytfe.resources.plan + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/policy.rst b/docs/source/api/resources/policy.rst new file mode 100644 index 00000000..b026a7fb --- /dev/null +++ b/docs/source/api/resources/policy.rst @@ -0,0 +1,8 @@ +Policies +======== + +.. automodule:: pytfe.resources.policy + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/policy_check.rst b/docs/source/api/resources/policy_check.rst new file mode 100644 index 00000000..ee24690d --- /dev/null +++ b/docs/source/api/resources/policy_check.rst @@ -0,0 +1,8 @@ +Policy Checks +============= + +.. automodule:: pytfe.resources.policy_check + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/policy_evaluation.rst b/docs/source/api/resources/policy_evaluation.rst new file mode 100644 index 00000000..b95dcd82 --- /dev/null +++ b/docs/source/api/resources/policy_evaluation.rst @@ -0,0 +1,8 @@ +Policy Evaluations +================== + +.. automodule:: pytfe.resources.policy_evaluation + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/policy_set.rst b/docs/source/api/resources/policy_set.rst new file mode 100644 index 00000000..50b25c76 --- /dev/null +++ b/docs/source/api/resources/policy_set.rst @@ -0,0 +1,8 @@ +Policy Sets +=========== + +.. automodule:: pytfe.resources.policy_set + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/policy_set_outcome.rst b/docs/source/api/resources/policy_set_outcome.rst new file mode 100644 index 00000000..d9255078 --- /dev/null +++ b/docs/source/api/resources/policy_set_outcome.rst @@ -0,0 +1,8 @@ +Policy Set Outcomes +=================== + +.. automodule:: pytfe.resources.policy_set_outcome + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/policy_set_parameter.rst b/docs/source/api/resources/policy_set_parameter.rst new file mode 100644 index 00000000..8596bdd2 --- /dev/null +++ b/docs/source/api/resources/policy_set_parameter.rst @@ -0,0 +1,8 @@ +Policy Set Parameters +===================== + +.. automodule:: pytfe.resources.policy_set_parameter + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/policy_set_version.rst b/docs/source/api/resources/policy_set_version.rst new file mode 100644 index 00000000..9615a1c7 --- /dev/null +++ b/docs/source/api/resources/policy_set_version.rst @@ -0,0 +1,8 @@ +Policy Set Versions +=================== + +.. automodule:: pytfe.resources.policy_set_version + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/projects.rst b/docs/source/api/resources/projects.rst new file mode 100644 index 00000000..c980d932 --- /dev/null +++ b/docs/source/api/resources/projects.rst @@ -0,0 +1,8 @@ +Projects +======== + +.. automodule:: pytfe.resources.projects + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/query_run.rst b/docs/source/api/resources/query_run.rst new file mode 100644 index 00000000..c917c2b5 --- /dev/null +++ b/docs/source/api/resources/query_run.rst @@ -0,0 +1,8 @@ +Query Runs +========== + +.. automodule:: pytfe.resources.query_run + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/registry_module.rst b/docs/source/api/resources/registry_module.rst new file mode 100644 index 00000000..971cd687 --- /dev/null +++ b/docs/source/api/resources/registry_module.rst @@ -0,0 +1,8 @@ +Registry Modules +================ + +.. automodule:: pytfe.resources.registry_module + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/registry_provider.rst b/docs/source/api/resources/registry_provider.rst new file mode 100644 index 00000000..0e03c41b --- /dev/null +++ b/docs/source/api/resources/registry_provider.rst @@ -0,0 +1,8 @@ +Registry Providers +================== + +.. automodule:: pytfe.resources.registry_provider + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/registry_provider_version.rst b/docs/source/api/resources/registry_provider_version.rst new file mode 100644 index 00000000..d64da443 --- /dev/null +++ b/docs/source/api/resources/registry_provider_version.rst @@ -0,0 +1,8 @@ +Registry Provider Versions +========================== + +.. automodule:: pytfe.resources.registry_provider_version + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/reserved_tag_key.rst b/docs/source/api/resources/reserved_tag_key.rst new file mode 100644 index 00000000..497e9eaf --- /dev/null +++ b/docs/source/api/resources/reserved_tag_key.rst @@ -0,0 +1,8 @@ +Reserved Tag Keys +================= + +.. automodule:: pytfe.resources.reserved_tag_key + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/run.rst b/docs/source/api/resources/run.rst new file mode 100644 index 00000000..1a3e0a4d --- /dev/null +++ b/docs/source/api/resources/run.rst @@ -0,0 +1,8 @@ +Runs +==== + +.. automodule:: pytfe.resources.run + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/run_event.rst b/docs/source/api/resources/run_event.rst new file mode 100644 index 00000000..2abae195 --- /dev/null +++ b/docs/source/api/resources/run_event.rst @@ -0,0 +1,8 @@ +Run Events +========== + +.. automodule:: pytfe.resources.run_event + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/run_task.rst b/docs/source/api/resources/run_task.rst new file mode 100644 index 00000000..2881b237 --- /dev/null +++ b/docs/source/api/resources/run_task.rst @@ -0,0 +1,8 @@ +Run Tasks +========= + +.. automodule:: pytfe.resources.run_task + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/run_trigger.rst b/docs/source/api/resources/run_trigger.rst new file mode 100644 index 00000000..494e4637 --- /dev/null +++ b/docs/source/api/resources/run_trigger.rst @@ -0,0 +1,8 @@ +Run Triggers +============ + +.. automodule:: pytfe.resources.run_trigger + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/ssh_keys.rst b/docs/source/api/resources/ssh_keys.rst new file mode 100644 index 00000000..f535a33a --- /dev/null +++ b/docs/source/api/resources/ssh_keys.rst @@ -0,0 +1,8 @@ +SSH Keys +======== + +.. automodule:: pytfe.resources.ssh_keys + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/state_version_outputs.rst b/docs/source/api/resources/state_version_outputs.rst new file mode 100644 index 00000000..f31029d6 --- /dev/null +++ b/docs/source/api/resources/state_version_outputs.rst @@ -0,0 +1,8 @@ +State Version Outputs +===================== + +.. automodule:: pytfe.resources.state_version_outputs + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/state_versions.rst b/docs/source/api/resources/state_versions.rst new file mode 100644 index 00000000..2c22f617 --- /dev/null +++ b/docs/source/api/resources/state_versions.rst @@ -0,0 +1,8 @@ +State Versions +============== + +.. automodule:: pytfe.resources.state_versions + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/variable.rst b/docs/source/api/resources/variable.rst new file mode 100644 index 00000000..30381d78 --- /dev/null +++ b/docs/source/api/resources/variable.rst @@ -0,0 +1,8 @@ +Variables +========= + +.. automodule:: pytfe.resources.variable + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/variable_sets.rst b/docs/source/api/resources/variable_sets.rst new file mode 100644 index 00000000..4fc2dc33 --- /dev/null +++ b/docs/source/api/resources/variable_sets.rst @@ -0,0 +1,8 @@ +Variable Sets +============= + +.. automodule:: pytfe.resources.variable_sets + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/workspace_resources.rst b/docs/source/api/resources/workspace_resources.rst new file mode 100644 index 00000000..b3386f30 --- /dev/null +++ b/docs/source/api/resources/workspace_resources.rst @@ -0,0 +1,8 @@ +Workspace Resources +=================== + +.. automodule:: pytfe.resources.workspace_resources + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/api/resources/workspaces.rst b/docs/source/api/resources/workspaces.rst new file mode 100644 index 00000000..f62f81bc --- /dev/null +++ b/docs/source/api/resources/workspaces.rst @@ -0,0 +1,8 @@ +Workspaces +========== + +.. automodule:: pytfe.resources.workspaces + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource diff --git a/docs/source/changelog.md b/docs/source/changelog.md new file mode 120000 index 00000000..699cc9e7 --- /dev/null +++ b/docs/source/changelog.md @@ -0,0 +1 @@ +../../CHANGELOG.md \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..70cb4bf6 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,90 @@ +# Copyright IBM Corp. 2025, 2026 +# SPDX-License-Identifier: MPL-2.0 + +from __future__ import annotations + +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "src")) + +project = 'pytfe' +copyright = 'IBM Corp. 2025, 2026' +author = 'HashiCorp, an IBM Corp.' +release = '0.1.4' +version = "0.1" + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx.ext.intersphinx", + "sphinx_autodoc_typehints", + "myst_parser", +] + +templates_path = ["_templates"] +exclude_patterns = [] + +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} + +autosummary_generate = False + +autodoc_default_options = { + "members": True, + "undoc-members": True, + "show-inheritance": True, + "member-order": "bysource", + "special-members": "__init__", + "exclude-members": "__weakref__, __dict__, __module__, __annotations__", +} + +autodoc_typehints = "description" +autodoc_typehints_format = "short" + +napoleon_google_docstring = True +napoleon_numpy_docstring = False +napoleon_include_init_with_doc = True +napoleon_use_param = True +napoleon_use_rtype = True +napoleon_preprocess_types = True +napoleon_attr_annotations = True + +always_document_param_types = True +typehints_fully_qualified = False +simplify_optional_unions = True + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "pydantic": ("https://docs.pydantic.dev/latest/", None), +} + +myst_enable_extensions = ["colon_fence", "deflist", "tasklist"] +myst_heading_anchors = 3 + +suppress_warnings = [ + # Models are re-exported from pytfe.models.__init__ AND their own submodule, + # causing duplicate cross-reference targets. This is expected behaviour. + "ref.python", + # pydantic internals trigger guarded-import warnings we cannot fix. + "sphinx_autodoc_typehints.guarded_import", +] + +html_theme = "sphinx_rtd_theme" +html_theme_options = { + "navigation_with_keys": True, + "vcs_pageview_mode": "blob", +} +html_context = { + "display_github": True, + "github_user": "hashicorp", + "github_repo": "python-tfe", + "github_version": "sphinx-docs", + "conf_py_path": "/docs/source/", +} +html_static_path = ["_static"] +html_title = f"pyTFE {release}" \ No newline at end of file diff --git a/docs/source/contributing.md b/docs/source/contributing.md new file mode 120000 index 00000000..44fcc634 --- /dev/null +++ b/docs/source/contributing.md @@ -0,0 +1 @@ +../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..fa87a6c5 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,35 @@ +pyTFE — Python SDK for HCP Terraform and Terraform Enterprise +============================================================== + +.. toctree:: + :maxdepth: 2 + :caption: Getting Started + + quickstart + installation + +.. toctree:: + :maxdepth: 2 + :caption: API Reference + + api/client + api/config + api/errors + api/models + api/resources + +.. toctree:: + :maxdepth: 1 + :caption: Developer Guide + + contributing + testing + releases + changelog + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 00000000..81b0f627 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,6 @@ +Installation +============ + +Install the package from PyPI:: + + pip install pytfe \ No newline at end of file diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 00000000..f5cd0016 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,4 @@ +Quickstart +========== + +This guide will be expanded with examples. For now, see the :doc:`installation` page to get started. \ No newline at end of file diff --git a/docs/source/releases.md b/docs/source/releases.md new file mode 120000 index 00000000..884e6820 --- /dev/null +++ b/docs/source/releases.md @@ -0,0 +1 @@ +../RELEASES.md \ No newline at end of file diff --git a/docs/source/testing.md b/docs/source/testing.md new file mode 120000 index 00000000..ad61e86f --- /dev/null +++ b/docs/source/testing.md @@ -0,0 +1 @@ +../TESTS.md \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index c8986fbd..aaaf02a6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -36,6 +36,14 @@ dev = [ "types-requests>=2.32.4.20250809", ] +docs = [ + "sphinx>=7.3", + "sphinx-autodoc-typehints>=2.2", + "myst-parser>=3.0", + "sphinx-rtd-theme>=3.0", + "sphinx-copybutton>=0.5", +] + [project.urls] "Repository" = "https://github.com/hashicorp/python-tfe" "Bug Tracker" = "https://github.com/hashicorp/python-tfe/issues" @@ -116,4 +124,5 @@ module = "tests.*" disallow_untyped_defs = false [tool.hatch.build.targets.sdist] -include = ["src/**", "README.md", "LICENSE", "docs/**"] \ No newline at end of file +include = ["src/**", "README.md", "LICENSE", "docs/**"] +exclude = ["docs/build/**"] \ No newline at end of file diff --git a/src/pytfe/models/policy_set.py b/src/pytfe/models/policy_set.py index 6bd7ca0c..31927b90 100644 --- a/src/pytfe/models/policy_set.py +++ b/src/pytfe/models/policy_set.py @@ -165,3 +165,8 @@ class PolicySetRemoveProjectsOptions(BaseModel): model_config = ConfigDict(populate_by_name=True, validate_by_name=True) projects: list[Project] = Field(default_factory=list) + + +# Resolve forward reference: PolicySetVersion.policy_set refers to PolicySet, +# which is defined in this module. Rebuild now that PolicySet is available. +PolicySetVersion.model_rebuild()