Package: ansible-specdoc
ansible-specdocA utility for dynamically generating documentation from an Ansible module's spec.This project was primarily designed for theLinode Ansible Collection.An example Ansible Collection usingansible-specdoccan be foundhere.Usageansible-specdoc[-h][-s][-nMODULE_NAME][-iINPUT_FILE][-oOUTPUT_FILE][-f{yaml,json,jinja2}][-j][-tTEMPLATE_FILE]GenerateAnsibleModuledocumentationfromspec.

options:-h,--helpshowthishelpmessageandexit-s,--stdinReadthemodulefromstdin.-nMODULE_NAME,--module-nameMODULE_NAMEThenameofthemodule(requiredforstdin)-iINPUT_FILE,--input_fileINPUT_FILEThemoduletogeneratedocumentationfrom.-oOUTPUT_FILE,--output_fileOUTPUT_FILEThefiletooutputthedocumentationto.-f{yaml,json,jinja2},--output_format{yaml,json,jinja2}Theoutputformatofthedocumentation.-j,--injectInjecttheoutputdocumentationintothe`DOCUMENTATION`,`RETURN`,and`EXAMPLES`fieldsofinputmodule.-tTEMPLATE_FILE,--template_fileTEMPLATE_FILEThefiletouseasthetemplatefortemplatedformats.-c,--clear_injected_fields,ClearstheDOCUMENTATION,RETURNS,andEXAMPLESfieldsinspecifiedmoduleandsetsthemtoanemptystring.Generating a templated documentation file:ansible-specdoc-fjinja2-tpath/to/my/template.md.j2-ipath/to/my/module.py-opath/to/output/file.mdDynamically generating and injecting documentation back into module constants:ansible-specdoc-j-ipath/to/my/module.pyNOTE: Documentation string injection requires that you haveDOCUMENTATION,RETURN, andEXAMPLESconstants defined in your module.Generating a raw documentation string (not recommended):ansible-specdoc-fyaml-ipath/to/my/module.pyImplementationImporting SpecDoc ClassesAll of theansible-specdocclasses can be imported into an Ansible module using the following statement:fromansible_specdoc.objectsimport*Alternatively, only specific classes can be imported using the following statement:fromansible_specdoc.objectsimportSpecDocMeta,SpecField,SpecReturnValue,FieldType,DeprecationInfoDeclaring Module MetadataTheansible-specdocspecification format requires that each module exports aSPECDOC_METAobject with the following structure:SPECDOC_META=SpecDocMeta(description=['Module Description'],requirements=['python >= 3.6'],author=['Author Name'],options=module_spec,examples=['example module usage'],return_values={'my_return_value':SpecReturnValue(description='A generic return value.',type=FieldType.string,sample=['sample response']),})Declaring Argument SpecificationEachSpecFieldobject translates to a parameter that can be rendered into documentation and passed into Ansible for specification.
These fields should be declared in a dict format as shown below:module_spec={'example_argument':SpecField(type=FieldType.string,required=True,description=['An example argument.'])}This dict should be passed into theoptionsfield of theSPECDOC_METAdeclaration.Passing Specification to AnsibleIn order to retrieve the Ansible-compatible spec dict, use theSPECDOC_META.ansible_specproperty.Other NotesTo preventansible-specdocfrom executing module code, please ensure that all module logic executes using the following pattern:if__name__=='__main__':main()To deprecate a module, specify thedeprecatedfield as follows:SPECDOC_META=SpecDocMeta(...deprecated=DeprecationInfo(alternative='my.new.module',removed_in='1.0.0',why='Reason for deprecation'))When deprecating a module, you will also need to update yourmeta/runtime.ymlfile.
Please refer to theofficial Ansible deprecation documentationfor more details.TemplatesThis repository provides anexample Markdown templatethat can be used in conjunction with the-targument.