Package: magicdoc
MagicDoc Automatated Project Documentation CLI Utility PackageNOTE: This Project is currently IN Beta as of this latest push on 02/19/2020.DescriptionDocumentation is a tedious task that most of the time is either ignored or completed with minimal detail and effort, potentially making it difficult for others to consume and adequately use the project being developed. For example, when building IaC for cloud environments, it can become an aggravating burden to take the time to document each module or project required to create and test the actual infrastructure necessary for personal or business workloads. MagicDoc is a tool that aims to help resolve that very problem and help to lessen and eventually eliminate that very burden. The goal of this project is to be able to very quickly and easily produce detailed, quality documentation within minutes, and without the need to write any markdown manually. A command here, a few sentences there, and poof, just like magic, MagicDoc has saved hours of time and created beautiful documentation for your project!Python VersionThis library is compatible with Python 3.6 and higher. It may work with earlier versions of Python3 but was not tested against anything earlier then 3.6. As Python 2.x is soon to be end of life, backward compatibility was not taken into consideration.InstallationThis library has been published toPyPiand can be installed via normal python package manager conventions such aspiporpoetry.pip3installmagicdocMagicDoc Commandsmagicdoc:Examples:magicdoc --helpArguments:NoneOptions:NoneMagicDoc Provider Sub-Command Groups:tf:Descripton:the tf subcommand sets the engine provider to terraform, loads the necessary terraform parsing libraries, and instantiates the necessary terraform objects to initialize terraform parsing capabilities.Examples:magicdoc tfmagicdoc tf --helpArguments:NoneOptions:verbose:Description:Enables / Disables Verbose loggingValue:boolFlag:--verbose, -vEnvironment Variable:MAGICDOC_TF_VERBOSERequired:NoDefault:Falseverbose_level:Description:|All application processes use standard logging format to include DEBUG, INFO, WARNING, and ERROR. By passing the -l flag the user user can specify the level of verbosity that they wish to see. Passing -l INFO for example will exclude debug logs, yet still allow INFO, WARNING, and ERROR messages to display in the cli console.Value:DEBUG | INFO | WARNING | ERRORFlag:--logging_level, -lEnvironment Variable:MAGICDOC_TF_VERBOSE_LEVELRequired:NoDefault:DEBUGdirectory:Description:|By default magicdoc will use the current directory path, however if an alternative directory is desired, then the -d flag can be used to specify the desired target directory path for the command execution.Value:Must be valid directory path.Flag:--dir, -dEnvironment Variable:MAGICDOC_TF_DIRECTORYRequired:NoDefault:Current Working Directoryexclude_dir:Description:|When searching a directory location for terraform files to parse, in the event that a directory exists in the parent target directory, that is not a desired search directory, it can be excluded using the -e flag. If specified, then the file search operation will ignore the specified subdirectory if it exists.Value:Must be valid directory path.Flag:--exclude_dir, -eEnvironment Variable:MAGICDOC_TF_EXCLUDE_DIRRequired:NoDefault:Noneconfig:Description:|The -c flag allows the user to specify the location of the target project magicdoc configuration file. By default magicdoc will look for the presense of a `magicdoc.yaml` file. Users can name the config file by another filename when creating the config, however the file must be a yaml formatted file, and if an alternative filename is specified then this option must be issued in order for magicdoc to be able to effectively find the config file that will be used to generate the documentation.Value:Must be valid file path.Flag:--config, -cEnvironment Variable:MAGICDOC_TF_CONFIGRequired:NoDefault:magicdoc.yamlno_recursion:Description:|The -nr flag is used to tell magicdoc to not search any subdirectories in a target project path. If the -nr flag is set, then only the parent target directory will be searched for terraform files, which will also automatically exclude subdirectories from variables and outputs search.Value:boolFlag:--no_recursion, -nrEnvironment Variable:MAGICDOC_TF_NO_RECURSIONRequired:NoDefault:True (Recursion enabled)Available Sub-Commands:-env-show-createMagicDoc TF Show EnvThemagicdoc tf envcommand will display information about the tf provider environment. It will display information such as if default template directory was found, what target directory path was specified, if a terraform object could be instantiated, meaning that magicdoc was able to find parsable terraform files in the target directory, and what flags where passed to the command. Its a simple check command for a quick look at how the tf provider environment is constructed when issued against a target project directory.env:Examples:magicdoc tf envArguments:NoneOptions:NoneMagicDoc TF Show CommandsThemagicdoc tf showcommand is a container for show subcommands. By itself this command will not return anything other then the help menu.Usage:magicdoctfshow[OPTIONS]COMMAND[ARGS]...

Options:--helpShowthismessageandexit.

Commands:filesDisplaytheterraformtargetprojectfilelists.gitDisplayTerraformProjectGitConfigDatagraphDisplayTerraformProjectdotGraphObjectoutputsDisplayTerraformProjectOutputsreleaseDisplayTerraformProjectLatestReleaserepoDisplayTerraformProjectGitRepositoryDatatreeDisplayTerraformProjectDirectoryTreevariablesDisplayTerraformProjectVariables.magicdoc tf show filesThemagicdoc tf show filescommand will display all of the .tf and .tfvar files in the target project directory that magicdoc was able to find and will use to perform its search and parse operation for Terraform variables and outputs.magicdoc tf show files:Examples:magicdoc tf show filesmagicdoc tf -d /path/to/module/sourcecode show filesArguments:NoneOptions:NoneMagicDocTerraformProjectFileSummary:========================================MagicDoc[tfshowfiles]CommandEnvironment:
GatheringTerraformProjectFiles...

Terraformfilesearchtargetdirectorylocation:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module->6terraformfile(s)foundintargetdirectory.->1tfvarfile(s)foundintargetdirectory.

Terraform.tffiles:====================outputs.tf
main.tf
variables.tf
example/outputs.tf
example/main.tf
example/variables.tf

Terraform.tfvarfiles:=======================example/env.tfvarsmagicdoc tf show variablesThemagicdoc tf show variablescommand will display an output of all terraform variables that were found in thevariables.tffile within the target project directory. Magicdoc will use the variables that it was able to parse from any found variable.tf files when constructing both the config file as well as the readme documentation.magicdoc show variables:Examples:magicdoc tf show variablesmagicdoc tf -d /path/to/module/sourcecode show variablesArguments:NoneOptions:include_examples:Description:Instructs the variables execution environment to include and parse files in any `example` or `examples` subdirectories located in the parent target project directory. By default directories named `example`, or `examples` are excluded from the file/variable/output search results, and are not parsed or included.Value:boolFlag:--include_examples, -1Environment Variable:MAGICDOC_TF_SHOW_VARIABLES_INCLUDE_EXAMPLESRequired:NoDefault:FalseEnvironment:VerboseAttributeSet:FalseLog:VerboseAttributeSet:FalseEnvironment:VerboseLevelAttributeSet:debug

MagicDocTerraformProjectVariableSummary:============================================IncludeExampleDirectories:False

MagicDoc[tfshowvariables]CommandEnvironment:
GatheringTerraformProjectFiles...

Parsingvariables.tffilesforTerraformvariables...
Scanningprojectdirectoryfordefinedmodulevariables...
Terraformvariablesearchtargetdirectorylocation:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module->8requiredterraformprojectvariablesfoundintargetproject:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module->13optionalterraformprojectvariablesfoundintargetproject:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module

TerraformProjectRequiredVariables:=====================================codebuild_project_name='Required Value'codebuild_project_desc='Required Value'codebuild_service_role_arn='Required Value'codebuild_source_type='Required Value'codebuild_source_url='Required Value'codebuild_vpc='Required Value'codebuild_subnet_list=['Required_Value_1''Required_Value_2']codebuild_sg_list=['Required_Value_1''Required_Value_2']TerraformProjectOptionalVariables:=====================================codebuild_timeout=15codebuild_badge='True'codebuild_artifact_type='NO_ARTIFACTS'codebuild_artifact_encryption='False'codebuild_encryption_key='NULL'codebuild_artifact_bucket='NULL'codebuild_artifact_path='/'codebuild_source_branch='master'codebuild_buildspec='buildspec.yml'codebuild_buildspec_type='FILENAME'codebuild_env_compute_type='BUILD_GENERAL1_SMALL'codebuild_env_image='aws/codebuild/standard:1.0'codebuild_env_type='LINUX_CONTAINER'magicdoc tf show outputsThemagicdoc tf show outputscommand will display an output of all terraform outputs that were found in theoutputs.tffile within the target project directory. Magicdoc will use the outputs that it was able to parse from any found outputs.tf files when constructing the readme documentation.magicdoc tf show outputs:Examples:magicdoc tf show outputsmagicdoc tf -d /path/to/module/sourcecode show outputsArguments:NoneOptions:include_examples:Description:Instructs the variables execution environment to include and parse files in any `example` or `examples` subdirectories located in the parent target project directory. By default directories named `example`, or `examples` are excluded from the file/variable/output search results, and are not parsed or included.Value:boolFlag:--include_examples, -iEnvironment Variable:MAGICDOC_TF_SHOW_VARIABLES_INCLUDE_EXAMPLESRequired:NoDefault:FalseEnvironment:VerboseAttributeSet:FalseLog:VerboseAttributeSet:FalseEnvironment:VerboseLevelAttributeSet:debug

MagicDocTerraformProjectOutputsSummary:===========================================IncludeExampleDirectories:False

MagicDoc[tfshowoutputs]CommandEnvironment:
GatheringTerraformProjectVariables...

Parsingoutputs.tffilesforTerraformoutputs...
Scanningprojectdirectoryfordefinedmoduleoutputs...
Terraformoutputsearchtargetdirectorylocation:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module->3terraformprojectoutputsfoundintargetproject:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Modulecodebuild_project_id={aws_codebuild_project.this.id}codebuild_project_arn={aws_codebuild_project.this.arn}codebuild_project_badge_url={aws_codebuild_project.this.badge_url}magicdoc tf show graphThemagicdoc tf show graphcommand will tell magicdoc to initialize the terraform project directory by issuing aterraform initon the directory. It will then run aterraform graphcommand and store the dot formatted graph data, and display it to the screen. Magicdoc will use this data to automatically construct, and render the terraform graph in PNG format if thedotbinary file can be found within the executing systems path. If magicdoc is successful in rendering the dot graph into a PNG file, the file will be placed into a images directory in the target project path, and then included in the readme documentation when renderend.magicdoc tf show graph:Examples:magicdoc tf show graphmagicdoc tf -d /path/to/module/sourcecode show graphArguments:NoneOptions:overwrite:Description:Instructs magicdoc to overwrite any existing .terraform directory if one is already found in the target project directory. If magicdoc does not find a .terraform directory, it will perform the `terraform init` run the graph dot file generation, and then remove the .terraform directory that it created in generating the graph data.Value:boolFlag:--overwrite, -oEnvironment Variable:MAGICDOC_TF_SHOW_GRAPH_OVERWRITERequired:NoDefault:FalseMagicDocTerraformProjectGraphdotStructure:===============================================OverwriteExisting.terraformDirectory:False

MagicDoc[tfshowgraph]CommandEnvironment:
GeneratingTerraformProjectGraph...

Generatingterraformgraphdotobject...
CLS->TFMagicDoc.terraform_init:Executing`terraforminit`ontargetprojectdirectory:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module

Initializingthebackend...

Initializingproviderplugins...
-Checkingforavailableproviderplugins...
-Downloadingpluginforprovider"aws"(hashicorp/aws)2.49.0...

Thefollowingprovidersdonothaveanyversionconstraintsinconfiguration,
sothelatestversionwasinstalled.

Topreventautomaticupgradestonewmajorversionsthatmaycontainbreaking
changes,itisrecommendedtoaddversion="..."constraintstothe
correspondingproviderblocksinconfiguration,withtheconstraintstrings
suggestedbelow.

*provider.aws:version="~> 2.49"Terraformhasbeensuccessfullyinitialized!

YoumaynowbeginworkingwithTerraform.Tryrunning"terraform plan"tosee
anychangesthatarerequiredforyourinfrastructure.AllTerraformcommands
shouldnowwork.

IfyoueversetorchangemodulesorbackendconfigurationforTerraform,
rerunthiscommandtoreinitializeyourworkingdirectory.Ifyouforget,other
commandswilldetectitandremindyoutodosoifnecessary.
CLS->TFMagicDoc.terraform_init:Executionof`terraforminit`completedsuccessfullyagainstthetargetdirectory:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module
digraph{compound="true"newrank="true"subgraph"root"{"[root] aws_codebuild_project.this"[label="aws_codebuild_project.this",shape="box"]"[root] aws_codebuild_webhook.this"[label="aws_codebuild_webhook.this",shape="box"]"[root] local.buildspec_file"[label="local.buildspec_file",shape="note"]"[root] local.codebuild_compute_env"[label="local.codebuild_compute_env",shape="note"]"[root] local.prebuilt_buildspec"[label="local.prebuilt_buildspec",shape="note"]"[root] output.codebuild_project_arn"[label="output.codebuild_project_arn",shape="note"]"[root] output.codebuild_project_badge_url"[label="output.codebuild_project_badge_url",shape="note"]"[root] output.codebuild_project_id"[label="output.codebuild_project_id",shape="note"]...etc}}magicdoc tf show gitThemagicdoc tf show gitcommand will display the git repository information that it was able to parse from the existing.git/configdirectory if one is present in the target project directory. Magicdoc will use the information that its able to parse from the .git/config file to form the requests to github to query for latest release data prior to document generation.magicdoc tf show git:Examples:magicdoc tf show gitmagicdoc tf -d /path/to/module/sourcecode show gitArguments:NoneOptions:auth:Description:Passed a git repository personal access token to magicdoc, and is used to construct the appropriate header auth request when requesting data from the configured git repository.Value:tokenFlag:--auth, -aEnvironment Variable:MAGICDOC_TF_SHOW_REPO_AUTHRequired:NoDefault:NoneMagicDocTerraformProjectGitConfig:======================================MagicDoc[tfshowgit]CommandEnvironment:
ParsingTerraformProjectGitConfig...

Attemptingtoparsetargetprojectgitconfig...{url='git@github.com:CloudMage-TF/TF-AWS-Test-Module.git'namespace='CloudMage-TF'name='TF-AWS-Test-Module.git'provider='github.com'}magicdoc tf show repoThemagicdoc tf show repocommand will display the git repository information that it was able to get from performing an API request to the repository found in the .git/config directory. The API collects just relevant information that was determined to be useful in aiding to provide data to the readme document that will be constructed. If the repository is a private repository an auth token can be passed using the -a flag.magicdoc tf show repo:Examples:magicdoc tf show repomagicdoc tf show repo -a "0123456789109876543210"magicdoc tf -d /path/to/module/sourcecode show repoArguments:NoneOptions:auth:Description:Passed a git repository personal access token to magicdoc, and is used to construct the appropriate header auth request when requesting data from the configured git repository.Value:tokenFlag:--auth, -aEnvironment Variable:MAGICDOC_TF_SHOW_REPO_AUTHRequired:NoDefault:NoneMagicDocTerraformProjectLatestRelease:==========================================GitAuthenticationTokenProvided:True


MagicDoc[tfshowrelease]CommandEnvironment:
SendingTerraformProjectGitReleaseRequest...


ProjectLatestRelease:=======================TF-AWS-ResourceNaming-ModuleLatestRelease:v1.0.5magicdoc tf show treeThemagicdoc tf show treecommand will construct and display an ascii style directory tree listing for the target project directory. During the data gathering stage, magicdoc will construct this tree view of the target project directory and include the output into the readme documentation.magicdoc tf show tree:Examples:magicdoc tf show treemagicdoc tf -d /path/to/module/sourcecode show treeArguments:NoneOptions:NoneEnvironment:VerboseAttributeSet:FalseLog:VerboseAttributeSet:FalseEnvironment:VerboseLevelAttributeSet:debugLog:VerboseLevelAttributeSet:debugEnvironment:TemplatePathSet:/Volumes/MacData/Work/CloudMage/PythonLibs/PyPkgs-MagicDoc/magicdoc/templatesEnvironment:DirectoryRecursionSet:False

Scanningprojectdirectoryforterraform.tfand.tfvarfiles...
Usage:main.pytfcreate[OPTIONS]COMMAND[ARGS]...CreateaMagicdocconfigorDocumentationforyourproject.


MagicDocTerraformProjectDirectoryTreeStructure:====================================================MagicDoc[tfshowtree]CommandEnvironment:
GatheringTerraformProjectOutputs...

.
├──outputs.tf
├──.DS_Store
├──Makefile
├──README.md
├──.gitignore
├──variables.tf
└──magicdoc.yamlMagicDoc TF Create CommandsThemagicdoc tf createcommand is a container for create subcommands. By itself this command will not return anything other then the help menu.Usage:magicdoc.pycreate[OPTIONS]COMMAND[ARGS]...Environment:VerboseAttributeSet:FalseLog:VerboseAttributeSet:FalseEnvironment:VerboseLevelAttributeSet:debugLog:VerboseLevelAttributeSet:debugEnvironment:TemplatePathSet:/Volumes/MacData/Work/CloudMage/PythonLibs/PyPkgs-MagicDoc/magicdoc/templatesEnvironment:DirectoryRecursionSet:False

Scanningprojectdirectoryforterraform.tfand.tfvarfiles...
Usage:main.pytfcreate[OPTIONS]COMMAND[ARGS]...CreateaMagicdocconfigorDocumentationforyourproject.

Options:--helpShowthismessageandexit.

Commands:configCreateamagicdocprojectconfigurationfile.docCreateaterraformmoduleorprojectREADME.mdfile.magicdoc tf create configCommand to generate a magicdoc config file for the target terraform project. The config file allows a user to supply additional information that will be rendered into the generated readme document. The command takes 1 option, being the type, identifying the type of project/the template used to render the document. The valid available option choices aremoduleandroot, although currently only module will work as a root template is still currently in development. If no option is selected, then magicdoc will default to module. Thecreate configcommand also takes a single optional argument that will allow the command issuer the ability to name the config file something other then magicdoc.yaml. If a custom config name is specified then subsequent commands to generate or regenerate the document will require that themagicdoc tf -c /path/to/confgoption is set. The file must be a yaml file extention, and this is forced, meaning that even if a custom file name is provided without a yaml extention, magicdoc will remove the extention and append .yaml to the custom config name.magicdoc tf create config -t <type> <filename>:Examples:magicdoc tf create configmagicdoc tf create config - modulemagicdoc tf create config -t module project.yamlmagicdoc tf -d /path/to/module/sourcecode create configmagicdoc tf -d /path/to/module/sourcecode create config -t modulemagicdoc tf -d /path/to/module/sourcecode create config -t module config.yamlArguments:filename:Description:The custom name that will be given to the config file that is produced and written to the target project directory.Value:Any string value that will be set as the project config file name.Required:No, If filename is specified, then magicdoc will use the provided filename to name the output config file.Default:magicdoc.yamlOptions:type:Description:The type of project that magicdoc will parse and build documentation for. When using the terraform provider, `module` and `root` are the only valid options.Note:Magicdoc currently only supports module documentation generation. A root template is currently in development.Value:module, rootFlag:--type, -tEnvironment Variable:MAGICDOC_TF_CREATE_CONFIG_TYPERequired:NoDefault:ModuleMagicDocTerraformDocumentationCreator:=========================================ConfigOutputFile:/Volumes/MacData/Work/Terraform/Modules/Documentation/TF-TestModule/magicdoc.yaml

MagicDocTerraformModuleConfigGenerator:[tfcreateconfig-tmodule<output_file>]:
AttemptingtoGatherTerraformProjectData...

Scanningprojectdirectoryfordefinedmodulevariables...

GeneratingTerraformModuleMagicdocConfig:magicdoc.yaml

MagicdocTerraformModuleconfigfile:magicdoc.yamlhasbeensuccessfullycreatedin:/Volumes/MacData/Work/Terraform/Modules/Documentation/TF-TestModule!magicdoc tf create docThemagicdoc tf create doccommand is the magic behind magicdoc. When this command is issued, magicdoc will run a data collection on all of the project outputs, variables, files, graph, git repository and release data, build the tree, and create the readme document. If aREADME.mdfile already exists in the target project directory then magicdoc will automatically backup this file, timestamp it, rename it as README__.bak and generate the new README file asREADME.mdin the target project directory.magicdoc tf create doc <-t type>:Examples:magicdoc tf create docmagicdoc tf create doc --helpmagicdoc tf create doc -t modulemagicdoc tf -d /path/to/module/sourcecode create doc -t modulemagicdoc tf -d /path/to/module/sourcecode create doc -t module -a "0123456789109876543210"Arguments:NoneOptions:type:Description:The type of project that magicdoc will parse and build documentation for. When using the terraform provider, `module` and `root` are the only valid options.Note:Magicdoc currently only supports module documentation generation. A root template is currently in development.Value:module, rootFlag:--type, -tEnvironment Variable:MAGICDOC_TF_CREATE_CONFIG_TYPERequired:NoDefault:Moduleauth:Description:Passed a git repository personal access token to magicdoc, and is used to construct the appropriate header auth request when requesting data from the configured git repository.Value:tokenFlag:--auth, -aEnvironment Variable:MAGICDOC_TF_SHOW_REPO_AUTHRequired:NoDefault:NoneMagicDocTerraformDocumentationCreator:=========================================OutputFile:README.md

MagicDocTerraformModuleDocGenerator:[tfcreatedoc-tmodule]:
AttemptingtoGatherTerraformProjectData...

MagicDocgitconfigfilenotfoundin/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module
Nogitinformationaboutthetargetprojectcanbeprovidedatthistime.
Scanningprojectdirectoryfordefinedmodulevariables...
Scanningprojectdirectoryfordefinedmoduleoutputs...

MagicDocTerraformDocumentationCreator:=========================================OutputFile:README.md

MagicDocTerraformModuleDocGenerator:[tfcreatedoc-tmodule]:
AttemptingtoGatherTerraformProjectData...

MagicDocgitconfigfilenotfoundin/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module
Nogitinformationaboutthetargetprojectcanbeprovidedatthistime.
Scanningprojectdirectoryfordefinedmodulevariables...
Scanningprojectdirectoryfordefinedmoduleoutputs...

GeneratingTerraformModuleReadmeDocumentation...
MagicdocTerraformModuledocumentationfile:README.mdhasbeensuccessfullycreatedin:/Volumes/MacData/Work/CloudMage/Terraform/TF-AWS-CodeBuild-Module!