ansible-network / collection_prep Goto Github PK

English isn't my first language, but did you mean "reviewers"? If "rewuires" is correct, please enlighten me and tell me what it means. I don't think I came across this word yet.

I'm curious, since there haven't been any commits since April, and no reactions on #88 from anyone with commit rights.

I stumbled upon this repository from some of the official collections . I love it for collections that will not be hosted on the Ansible Document site that want similar style docs. The roles I have wrote for my work, I have wrote module like YAML docs for the variables inside the README file.

Would there be any objections on including generated docs for role variables? It could be a .py file inside the role directory that would include a DOCUMENTATION block to parse.

We have an issue Consider using true/false for all booleans in docs in community.vmware. The examples are documented manually, I can change them.

But we use ansible-network/collection_prep there to create the docs. I might be wrong, but it looks to me that it uses yes / no when documenting booleans. At least, it didn't update the documentation to true / false when I ran it to create ansible-collections/community.vmware#1661. Am I correct, or do I overlook something?

If I'm correct, please change ansible-network/collection_prep to document true / false instead of yes / no for booleans.

ansible-community/community-team#60

The following warning is currently added to the README:

For collections that support Ansible 2.9, please ensure you update your `network_os` to use the 
fully qualified collection name (for example, `cisco.ios.ios`). 

While ansible-network is nominally scoped to network modules, many of the release related tools have ended up with a much broader scope and are just maintained by the network engineering team. As far as I can tell this warning only applies to a handful of collections, however it's currently being spammed into any that use collection_prep. Please make this warning optional and provide a mechanism to disable it which can be stored in the repo.

We have pre-commit hooks, which is great, but they need a git ref to point to in order to work. Currently I just stuck master in there, but pre-commit is smart enough to cache the repo if the ref hasn't changed, so we'll never get updates that way.

1. If we tag releases, it would add a little overhead to pushing changes here, but make it easier for humans to update the ref (rather than having to look up a git sha)

2. As I write that, the whole "humans doing things" jumps out at me, so we could make a second pre-commit hook to read git ls-remote git://github.com/ansible-network/collection_prep.git refs/heads/master | cut -f 1 or something, compare that to the saved ref and update the file if necessary (which will abort the commit, and adding the change will then run the appropriately updated version. This pleases me greatly, but is probably too much of a Rube Goldberg machine to rely on.

We have some static documentation in docs/docsite. It looks like collection_prep_add_docs -p . removes everything in docs. It would be great if we could tell collection_prep_add_docs to ignore / not remove some files or directories.

Please see ansible-collections/community.vmware#1003 for more information.

Issue description

Running collection_prep_add_docs fails with Traceback
jinja2.exceptions.UndefinedError: 'ansible.parsing.yaml.objects.AnsibleMapping object' has no attribute 'choices'
Also impacts pre-commit hooks

Traceback

(dev38)  sagpaul@sagpaul  ~/MyVnvs/WorkA1/collections/ansible_collections/cisco  collection_prep_add_docs -p ./ios 
INFO     Setting collection name to cisco.ios 
INFO     Setting GitHub repository url to https://github.com/ansible-collections/cisco.ios 
INFO     Purging content from directory /home/sagpaul/MyVnvs/WorkA1/collections/ansible_collections/cisco/ios/docs 
INFO     Making docs directory /home/sagpaul/MyVnvs/WorkA1/collections/ansible_collections/cisco/ios/docs 
INFO     Process content in /home/sagpaul/MyVnvs/WorkA1/collections/ansible_collections/cisco/ios/plugins/cliconf 
INFO     Processing /home/sagpaul/MyVnvs/WorkA1/collections/ansible_collections/cisco/ios/plugins/cliconf/ios.py 
Traceback (most recent call last): 
 File "/home/sagpaul/MyVnvs/dev38/bin/collection_prep_add_docs", line 8, in <module> 
   sys.exit(main()) 
 File "/home/sagpaul/MyVnvs/dev38/lib/python3.8/site-packages/collection_prep/cmd/add_docs.py", line 548, in main 
   content = process(collection=collection, path=path) 
 File "/home/sagpaul/MyVnvs/dev38/lib/python3.8/site-packages/collection_prep/cmd/add_docs.py", line 385, in process 
   fd.write(template.render(doc)) 
 File "/home/sagpaul/MyVnvs/dev38/lib/python3.8/site-packages/jinja2/environment.py", line 1289, in render 
   self.environment.handle_exception() 
 File "/home/sagpaul/MyVnvs/dev38/lib/python3.8/site-packages/jinja2/environment.py", line 924, in handle_exception 
   raise rewrite_traceback_stack(source=source) 
 File "/home/sagpaul/MyVnvs/dev38/lib/python3.8/site-packages/collection_prep/cmd/plugin.rst.j2", line 102, in top-l
evel template code 
   {% for key, value in options|dictsort recursive %} 
 File "/home/sagpaul/MyVnvs/dev38/lib/python3.8/site-packages/collection_prep/cmd/plugin.rst.j2", line 156, in templ
ate 
   {% if value.default is defined and value.default not in value.choices %} 
jinja2.exceptions.UndefinedError: 'ansible.parsing.yaml.objects.AnsibleMapping object' has no attribute 'choices'

checked with Vyos & Ios

It looks like collection_prep_add_docs -p . looks for plugins/doc_fragments in the collection search path, not in the current directory (see community.vmware#1062 ff).

I think that not searching for plugins/doc_fragments in the directory defined with -p breaks the principle of least astonishment.

Hi all,

Importing a large number of auto-generated files make me file a bit uncomfortable. I would prefer to avoid duplicated data in the repository, and this can also confuse the contributors. In addition, we can still face situation where the modules and the .rst will be out-of-sync. Also, if we modify collection_prep, we will need to regenerate the .rst of all the collection repositories.

I understand the README.md change has to be imported in the repository, but can we generate the .rst files just before we build the release tarballs? This could even be part of the zuul release pipeline.