{"id":21480143,"url":"https://github.com/linode/ansible-specdoc","last_synced_at":"2025-07-15T12:31:38.217Z","repository":{"id":65797935,"uuid":"560035546","full_name":"linode/ansible-specdoc","owner":"linode","description":"A utility for dynamically generating Ansible Collection documentation.","archived":false,"fork":false,"pushed_at":"2024-04-29T19:54:46.000Z","size":137,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-30T19:43:14.072Z","etag":null,"topics":["ansible","ansible-collection","ansible-galaxy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-31T15:52:18.000Z","updated_at":"2024-06-21T07:54:34.711Z","dependencies_parsed_at":"2024-03-04T18:32:56.036Z","dependency_job_id":"cd7a8f52-a7f8-458f-bd83-10a049769dfa","html_url":"https://github.com/linode/ansible-specdoc","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linode%2Fansible-specdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linode%2Fansible-specdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linode%2Fansible-specdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linode%2Fansible-specdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linode","download_url":"https://codeload.github.com/linode/ansible-specdoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226038794,"owners_count":17564046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible","ansible-collection","ansible-galaxy"],"created_at":"2024-11-23T12:13:16.722Z","updated_at":"2024-11-23T12:13:17.650Z","avatar_url":"https://github.com/linode.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ansible-specdoc\n\nA utility for dynamically generating documentation from an Ansible module's spec. \n\nThis project was primarily designed for the [Linode Ansible Collection](https://github.com/linode/ansible_linode).\n\nAn example Ansible Collection using `ansible-specdoc` can be found [here](https://github.com/linode/ansible-specdoc-example).\n\n## Usage\n\n```sh\nansible-specdoc [-h] [-s] [-n MODULE_NAME] [-i INPUT_FILE] [-o OUTPUT_FILE] [-f {yaml,json,jinja2}] [-j] [-t TEMPLATE_FILE]\n\nGenerate Ansible Module documentation from spec.\n\noptions:\n  -h, --help            show this help message and exit\n  -s, --stdin           Read the module from stdin.\n  -n MODULE_NAME, --module-name MODULE_NAME\n                        The name of the module (required for stdin)\n  -i INPUT_FILE, --input_file INPUT_FILE\n                        The module to generate documentation from.\n  -o OUTPUT_FILE, --output_file OUTPUT_FILE\n                        The file to output the documentation to.\n  -f {yaml,json,jinja2}, --output_format {yaml,json,jinja2}\n                        The output format of the documentation.\n  -j, --inject          Inject the output documentation into the `DOCUMENTATION`, `RETURN`, and `EXAMPLES` fields of input module.\n  -t TEMPLATE_FILE, --template_file TEMPLATE_FILE\n                        The file to use as the template for templated formats.\n  -c, --clear_injected_fields,\n                        Clears the DOCUMENTATION, RETURNS, and EXAMPLES fields in specified module and sets them to an empty string.\n```\n\n---\n\n#### Generating a templated documentation file:\n\n```shell\nansible-specdoc -f jinja2 -t path/to/my/template.md.j2 -i path/to/my/module.py -o path/to/output/file.md\n```\n\n---\n\n#### Dynamically generating and injecting documentation back into module constants:\n\n```shell\nansible-specdoc -j -i path/to/my/module.py\n```\n\nNOTE: Documentation string injection requires that you have `DOCUMENTATION`, `RETURN`, and `EXAMPLES` constants defined in your module.\n\n---\n\n#### Generating a raw documentation string (not recommended):\n\n```shell\nansible-specdoc -f yaml -i path/to/my/module.py\n```\n\n## Implementation\n\n### Importing SpecDoc Classes\n\nAll of the `ansible-specdoc` classes can be imported into an Ansible module using the following statement:\n\n```python\nfrom ansible_specdoc.objects import *\n```\n\nAlternatively, only specific classes can be imported using the following statement:\n\n```python\nfrom ansible_specdoc.objects import SpecDocMeta, SpecField, SpecReturnValue, FieldType, DeprecationInfo\n```\n\n### Declaring Module Metadata\nThe `ansible-specdoc` specification format requires that each module exports a `SPECDOC_META` object with the following structure:\n\n```python\nSPECDOC_META = SpecDocMeta(\n    description=['Module Description'],\n    requirements=['python \u003e= 3.6'],\n    author=['Author Name'],\n    options=module_spec,\n    examples=[\n        'example module usage'\n    ],\n    return_values={\n        'my_return_value': SpecReturnValue(\n            description='A generic return value.',\n            type=FieldType.string,\n            sample=['sample response']\n        ),\n    }\n)\n```\n\n### Declaring Argument Specification\n\nEach `SpecField` object translates to a parameter that can be rendered into documentation and passed into Ansible for specification.\nThese fields should be declared in a dict format as shown below:\n\n```python\nmodule_spec = {\n    'example_argument': SpecField(\n        type=FieldType.string,\n        required=True,\n        description=['An example argument.']\n    )\n}\n```\n\nThis dict should be passed into the `options` field of the `SPECDOC_META` declaration.\n\n### Passing Specification to Ansible\n\nIn order to retrieve the Ansible-compatible spec dict, use the `SPECDOC_META.ansible_spec` property.\n\n### Other Notes\n\nTo prevent `ansible-specdoc` from executing module code, please ensure that all module logic executes using the following pattern:\n\n```python\nif __name__ == '__main__':\n    main()\n```\n\n---\n\nTo deprecate a module, specify the `deprecated` field as follows:\n\n```python\nSPECDOC_META = SpecDocMeta(\n    ...\n    deprecated=DeprecationInfo(\n        alternative='my.new.module',\n        removed_in='1.0.0',\n        why='Reason for deprecation'\n    )\n)\n```\n\nWhen deprecating a module, you will also need to update your `meta/runtime.yml` file.\nPlease refer to the [official Ansible deprecation documentation](https://docs.ansible.com/ansible/latest/dev_guide/module_lifecycle.html#deprecating-modules-and-plugins-in-a-collection) for more details.\n\n## Templates\n\nThis repository provides an [example Markdown template](./template/module.md.j2) that can be used in conjunction with the `-t` argument.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinode%2Fansible-specdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinode%2Fansible-specdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinode%2Fansible-specdoc/lists"}