Antsibull-docs: is description for check_mode and diff_mode required?

Get Help
, ,
1

Hi,

I’m running into some issues building a docsite with antsibull-doc.

Given the following module mve_antsibull_doc.py:

#!/usr/bin/python

from __future__ import (absolute_import, division, print_function)
__metaclass__ = type

DOCUMENTATION = '''
---
module: mve_antsibull_doc
short_description: TBD
description: TBD
attributes:
    check_mode:
        support: full
    diff_mode:
        support: full
options:
    name:
        description: TBD
        required: false
        type: str

author:
    - spike
'''

EXAMPLES = '''
- name: Random example
  mve_antsibull_doc:
    name: hello
'''

RETURN = '''
name:
    description: TBD
    type: str
    returned: always
'''

from ansible.module_utils.basic import AnsibleModule

def main():
    return

if __name__ == '__main__':
    main()

I’m running into the following problem:

$ antsibull-docs plugin --plugin-type module --dest-dir /tmp/doc/rst/ my.utils.mve_antsibull_doc 
Cannot parse documentation:
10 validation errors for ModuleDocSchema
doc -> attributes -> check_mode -> description
  field required (type=value_error.missing)
doc -> attributes -> check_mode -> description
  field required (type=value_error.missing)
doc -> attributes -> check_mode -> membership
  field required (type=value_error.missing)
doc -> attributes -> check_mode -> description
  field required (type=value_error.missing)
doc -> attributes -> check_mode -> platforms
  field required (type=value_error.missing)
doc -> attributes -> diff_mode -> description
  field required (type=value_error.missing)
doc -> attributes -> diff_mode -> description
  field required (type=value_error.missing)
doc -> attributes -> diff_mode -> membership
  field required (type=value_error.missing)
doc -> attributes -> diff_mode -> description
  field required (type=value_error.missing)
doc -> attributes -> diff_mode -> platforms
  field required (type=value_error.missing)

When running (as per documentation)

antsibull-docs sphinx-init --use-current --squash-hierarchy --dest-dir /tmp/doc/ my.utils
cd /tmp/doc/
./build.sh

the html files are generated but only contain the error messages:

Screenshot_20240217_010209
Screenshot_20240217_010209425×447 47.9 KB

Works fine if I add an arbitrary description key to check_mode and diff_mode.
I’ve checked Module format and documentation — Ansible Community Documentation but that doesn’t list the attributes field at all. However, most (if not all) of the modules in lib/ansible and community.general do.

I’m running

  • antsibull-docs 2.7.0
  • antsibull-docs-parser 1.0.0

Is this a bug?

2

You’re missing the other thing that the modules in question have, which is a doc fragment with the common attribute documentation.

You’re not required to use these attributes (you can define your own or even use ones with the same name but different descriptions), but if you want to use them you have to explicitly pull them in.

3

D’oh! Thanks a bunch!

4

The module documentation format you’re referencing (Module format and documentation — Ansible Documentation) does not describe attributes at all, so yes, it doesn’t mention that the description is required, but it also doesn’t mention the reverse :slight_smile:

In general you should also run ansible-test sanity --docker -v on your module first, that would have also pointed out these problems.

5

PR to document attributes: Document attributes by felixfontein · Pull Request #1130 · ansible/ansible-documentation · GitHub

1 Like
6

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.