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:
- $(cwd)/mkdocs.yml mkdocs configuration file
- $(cwd)/$(docs)/index.md provider documentation file
- $(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.
- $(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
const ( // Exit status denoting success ExitSuccess = 0 // Exit status denoting error ExitError = 1 )
Exit status constants
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")
This section is empty.
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.
This section is empty.