autodoc

package
Version: v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 11, 2022 License: MPL-2.0 Imports: 7 Imported by: 4

Documentation

Overview

Package autodoc contains the engine for the autodoc command line application to automatically generate mkdocs-style documentation for the provider. This application uses text templates and feeds them the parsed schema data to produce up-to-date documentation.

This application takes the following arguments:

-provider=NAME
  Name of the Terraform provider. Defaults to "Terraform Provider".
-root
  The root directory to being placing output documentation files. Defaults
  to the current working directory. The mkdocs.yml file will be placed
  in this location.
-docs-dir
  The name of the directory to place generated documentation. This will
  be placed under the parameter supplied for -root. Defaults to 'docs'.
  The autogenerated mkdocs.yml file will have its 'docs_dir' set to this
  value.
-templates-dir
  The directory to search for template files. Templates are searched
  and loaded recursively from this directory. Defaults to
  '$(cwd)/templates'
-template-ext
  File extension for template files. Defaults to '.template'

Arguments can be assigned values by using the '=' operator:

$> autodoc -root='/my/path'

This application will exit 1 on error, 0 on success.

The following files are generated as output by the application. Let $(cwd) be the value supplied to -root, and $(docs) be the value supplied to -docs-dir:

  1. $(cwd)/mkdocs.yml mkdocs configuration file
  2. $(cwd)/$(docs)/index.md provider documentation file
  3. $(cwd)/$(docs)/resources/*.md All resource documentation. There will be one md file for each resource. The resource files will be named corresponding to its name in the provider's ResourcesMap.
  4. $(cwd)/$(docs)/data-sources/*.md All datasource documentation. There will be one md file for each datasource. The datasource files will be named corresponding to its name in the provider's DataSourcesMap.

This application assumes the user has read/write access to all output paths

This application uses the following template associations for each output file:

mkdocs.yml.template
  $(cwd)/mkdocs.yml => mkdocs configuration
index.md.template
  $(cwd)/$(docs)/index.md => Provider documentation
resource.md.template
  $(cwd)/$(docs)/resources/*.md => Documentation for all resources
datasource.md.template
  $(cwd)/$(docs)/data-sources/*.md => Documentation for all data sources

Index

Constants

View Source
const (
	// Exit status denoting success
	ExitSuccess = 0
	// Exit status denoting error
	ExitError = 1
)

Exit status constants

View Source
const (
	// The meta attribute. If an attribute has this name, autodoc will interpret
	// it as a special tag and parses its description for more resource-level
	// metadata information. This attribute is never included in the docs.
	MetaAttribute = "__meta__"
	// Metadata tag to signal that this resource cannot be created. This should
	// be in the description of the meta attribute. This tag does
	// not accept a value. The default behavior assumes the resource can be
	// created. This over-rides that behavior.
	MetaNotCreatable = "@NOTCREATABLE"
	// Metadata tag to signal that this resource cannot be deleted. This should
	// be in the description of the meta attribute. This tag does not
	// accept a value. The default behavior assumes the resource can be
	// deleted. This over-rides that behavior.
	MetaNotDeletable = "@NOTDELETABLE"
	// Metadata tag to signal that this resource cannot be updated. This should
	// be in the description of the meta attribute. This tag does
	// not accept a value. The default behavior assumes the resource can be
	// updated. this over-rides that behavior.
	MetaImmutable = "@IMMUTABLE"
	// Metadata tag that provides more information. This should be in the
	// description of the meta attribute. This tag accepts a value corresponding
	// the summary for this resource.
	MetaSummary = "@SUMMARY"
	// Metadata tag to provide an example value for the resource's argument.
	// This should be in the description for one of the resource's arguments.
	// This tag accepts a value corresponding to an example value for this
	// argument.
	MetaExample = "@EXAMPLE"
	// Metadata tag to denote a resource's attributed as unexported.  Unexported
	// attributes are not exposed to other resources. The default behavior is
	// to assume the attribute is exported. This will over-ride that behavior.
	// This tag does not accept a value.
	MetaUnexported = "@UNEXPORTED"
)

Metadata tags. These can be set in the description field of the schema to provide extra information when generating docs. Tags should be separated by a space (ie: "@FOO @BAR" not "@FOO@BAR"). If a tag supports a value, the value for that tag should come after the tag, separated by a space (ie: "@FOO value for foo tag @BAR")

Variables

This section is empty.

Functions

func Document

func Document(provider *schema.Provider) []error

Document is the entry point into autodoc execution. The command line arguments and templates are read and parsed. The provider reference is parsed to generate the documentation. This function will return a list of errors. If this list is empty, no errors were encountered.

func Usage

func Usage()

Usage prints usage information to stdout

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL