Merge pull request #2 from hfern/hgf/docs

Add Sphinx docs

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file for Sphinx projects
+# 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-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_create_environment:
+      - python -m pip install poetry
+    post_install:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true

Makefile

@@ -42,3 +42,11 @@ test: test-format test-python test-pyre
 
 build:
 	$(HIDE)$(POETRY) build
+
+doc:
+	$(HIDE)$(POETRY) run sphinx-build -M html ./docs ./docs/_build -W
+
+
+clean:
+	$(HIDE)rm -rf ./dist
+	$(HIDE)rm -rf ./docs/_build

README.md

@@ -58,7 +58,7 @@ must be named in the form of `terraform-provider-<providername>`.
 This means that you must your [entrypoint](https://setuptools.pypa.io/en/latest/userguide/entry_point.html)
 similarly.
 
-```toml filename="pyproject.toml"
+```toml
 [project.scripts]
 terraform-provider-myprovider = "mypackage.main:main"
 ```
@@ -70,7 +70,7 @@ In order to get TF to use your provider, you must tell TF to run your provider f
 This is done by editing the `~/.terraformrc` or `~/.tofurc` file,
 and setting the path to your virtual environment's `bin` directory (which contains the `terraform-provider-myprovider` script).
 
-```hcl filename="~/.terraformrc"
+```hcl
 provider_installation {
   dev_overrides {
       "tf.mydomain.com/mypackage" = "/path/to/your/.venv/bin"
@@ -82,9 +82,9 @@ provider_installation {
 
 ### Using the Provider
 
-Now you can use your provider in Terraform by specifying it in the `provider` block.
+Now you can use your provider in Terraform by specifying it in the `provider` block in your `main.tf`.
 
-```hcl filename="main.tf"
+```hcl
 terraform {
   required_providers {
     myprovider = { source  = "tf.mydomain.com/mypackage"}
@@ -107,15 +107,15 @@ Attributes can be a combination of `required`, `computed`, and `optional`.
 The values of these flags determine how the attribute is treated by TF and the framework.
 
 | Required | Computed | Optional | Behavior                                                                                 |
-|:--------:|:--------:|:--------:|------------------------------------------------------------------------------------------|
+|----------|----------|----------|------------------------------------------------------------------------------------------|
 |          |          |          | _Invalid combination._ You must have at least one flag set.                              |
-|          |          |    X     | Fields may be set. TODO: Have default values.                                            |
-|          |    X     |          | Computed fields are read-only, value is set by the server and cannot be set by the user. |
-|          |    X     |    X     | Field may be set. If not, uses value from server.                                        |
-|    X     |          |          | Required fields must be present in the configuration.                                    |                                                             |
-|    X     |          |    X     | _Invalid combination._                                                                   |
-|    X     |    X     |          | _Invalid combination._                                                                   |
-|    X     |    X     |    X     | _Invalid combination._                                                                   |
+|          |          | X        | Fields may be set. TODO: Have default values.                                            |
+|          | X        |          | Computed fields are read-only, value is set by the server and cannot be set by the user. |
+|          | X        | X        | Field may be set. If not, uses value from server.                                        |
+| X        |          |          | Required fields must be present in the configuration.                                    |
+| X        |          | X        | _Invalid combination._                                                                   |
+| X        | X        |          | _Invalid combination._                                                                   |
+| X        | X        | X        | _Invalid combination._                                                                   |
 
 
 ## Types

docs/.gitignore

@@ -0,0 +1 @@
+_build

docs/Makefile

@@ -0,0 +1,21 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+HIDE		  ?= @
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= poetry run sphinx-build
+SOURCEDIR     = .
+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
+	$(HIDE)$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/api.rst

@@ -0,0 +1,114 @@
+***
+API
+***
+
+.. py:module:: tf
+
+Execution Interface
+===================
+
+The execution interface provides program entrypoints for OpenTofu to run your provider.
+
+
+.. autofunction:: tf.runner.run_provider
+
+An installation utility is provided to install your provider.
+
+.. autofunction:: tf.runner.install_provider
+
+You are expected to provide a `main.py` file in your provider package with a method
+(set as an entrypoint)
+that calls
+:func:`~tf.runner.run_provider` and :func:`~tf.runner.install_provider`.
+
+Provider Interface
+==================
+
+To implement a provider, you must subclass :class:`~tf.iface.Provider` and implement the methods.
+Essentially a Provider answers some questions about itself, allows configuration of itself,
+and provides a list of :class:`~tf.iface.DataSource` and :class:`~tf.iface.Resource` classes it supports.
+
+.. autoclass:: tf.iface.Provider
+   :members:
+
+The :class:`~tf.iface.AbstractResource` represents an *element*: a data source or a resource.
+Both types of elements must be named and have a schema.
+
+.. autoclass:: tf.iface.AbstractResource
+   :members:
+
+Data Sources
+------------
+
+A DataSource is the simplest element to implement -- it's stateless and only provides data.
+A DataSource must implement one method, :func:`~tf.iface.DataSource.read`,
+and may optionally implement :func:`~tf.iface.DataSource.validate_config`.
+
+.. autoclass:: tf.iface.DataSource
+   :show-inheritance:
+   :members:
+
+Resources
+---------
+
+A Resource is a more complex element to implement -- it's stateful and provides data and actions.
+You must implement:
+:func:`~tf.iface.AbstractResource.get_name` and, :func:`~tf.iface.AbstractResource.get_schema`
+as well as
+:func:`~tf.iface.Resource.create`, :func:`~tf.iface.Resource.read`, :func:`~tf.iface.Resource.update`,
+and :func:`~tf.iface.Resource.delete` to control the lifecycle of the resource.
+
+You may also optionally implement :func:`~tf.iface.Resource.import_` and :func:`~tf.iface.Resource.plan`,
+:func:`~tf.iface.Resource.upgrade`, and :func:`~tf.iface.Resource.validate` to further hook into the lifecycle.
+
+
+.. autoclass:: tf.iface.Resource
+   :show-inheritance:
+   :members:
+
+
+State
+-----
+
+*State* is a snapshot of your resource at a point in time.
+It is a dictionary of field names to values.
+
+.. autoclass:: tf.iface.State
+   :members:
+
+
+Schemas
+============
+
+Every resource must be specified with a schema.
+A schema consists of a version, a set of fields, and a set of block types.
+
+.. autoclass:: tf.schema.Schema
+    :members:
+
+Attributes
+----------
+
+An attribute is a field in a schema. It ties a field name to a type and a set of behaviors.
+
+.. autoclass:: tf.schema.Attribute
+    :members:
+
+Blocks
+------
+
+Blocks are a way to group fields together in a schema. They are akin to sub-resources.
+Blocks define their own attributes and may have nested blocks.
+
+.. autoclass:: tf.schema.Block
+    :members:
+
+Types
+-----
+
+.. autoclass:: tf.types.Number
+.. autoclass:: tf.types.String
+.. autoclass:: tf.types.Bool
+.. autoclass:: tf.types.NormalizedJson
+.. autoclass:: tf.types.List
+.. autoclass:: tf.types.Set

docs/conf.py

@@ -0,0 +1,42 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'tf'
+copyright = '2024, Hunter Fernandes'
+author = 'Hunter Fernandes'
+release = '1.0.2'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autosummary",
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx_mdinclude',
+    # 'sphinx_immaterial',
+    # "sphinx_immaterial.apidoc.python.apigen",
+]
+
+autosummary_generate = True
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+python_apigen_modules = {
+      "tf": "api",
+}
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+# html_theme = 'sphinx_immaterial'
+html_static_path = ['_static']

docs/index.rst

@@ -0,0 +1,10 @@
+..  toctree::
+    :maxdepth: 1
+    :caption: Contents:
+
+    api.rst
+
+* :ref:`genindex`
+* :ref:`search`
+
+..   mdinclude:: ../README.md

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd