Add documentation about where to place modules

[jiv-e]

Issue Type:

Documentation Report

Ansible Version:

ansible 1.6

Environment:

N/A

Summary:

Current documentation is not clear about where to put custom modules. Please add a section about this on http://docs.ansible.com/developing_modules.html. E.g. With subtitle "Where To Put Your Modules".

Steps To Reproduce:

1. See http://docs.ansible.com/developing_modules.html.
2. Try to find documentation about where to put your modules.

Expected Results:

Documentation is describing all the paths where the custom modules are picked up by Ansible and all the procedures how to get other directories included. Examples of these procedures are presented.

I read the issue comment linked below and found out that you can put the modules in ./library folder relative to your playbook file. I want also to include custom modules to roles and noticed that ./library in the role directory was also included. I expect at least these options to be documented. I would make a pull request, but I'm not sure of all the options available.

References:

• Dynamically loadable modules #6973 (comment)

Actual Results:

Found:
"Modules can be written in any language and are found in the path specified by ANSIBLE_LIBRARY or the --module-path command line option."

• No context provided which makes this vague
• Written on one line paragraph that is hard to notice. Subtitle would help a lot.
• Other options missing
• No examples

Found under 'Documenting Your Module' --> 'Building & Testing':
"Put your completed module file into the ‘library’ directory and then run the command: make webdocs."

• No context provided. Where is the library folder? Where should the command be run?
• I would not start to look under the 'Documenting Your Module' about this topic

[fiunchinho]

Any news on this? I actually don't know how to include custom modules in ./library that are folders. I can get it to work if module is just a module.py file, but it does not work if it's inside ./library/module/module.py

[jhawkesworth]

This is documented here:

http://docs.ansible.com/ansible/intro_configuration.html#library

Is that what you mean?

[fiunchinho]

It works when I place files directly on the folder. But it does not when I put folders containing the files inside the library folder

[jhawkesworth]

so if you want to add subfolders, just list them in your ansible.cfg?

library = /etc/ansible/library:/etc/ansible/library/module1:/etc/ansible/library/module2

Or are you saying that does that not work?

If I recall you can also have a library folder inside your role.

[fiunchinho]

I was thinking on using git submodules to bring the code for my modules, so I wouldn't know before hand which folders to add to the ansible.cfg :/
Any other ideas?

[tyll]

I would also like to know how to best include other modules that are git submodules such as https://github.com/brainly/ansible-modules/blob/master/library/zone_serial it seems to work fine in ansible < 2.0 but just adding submodules to the library directory in the playbooks dir does not help

[jimi-c]

Hi @jiv-e (and @tyll), there is a mention of the ./library path in the developing modules doc, as well as a section entitled "Module Paths", which covers similar subject matter. As such, we'll go ahead and close this issue now.

If you have any further questions, please let us know by stopping by one of the two mailing lists, as appropriate:

• https://groups.google.com/forum/#!forum/ansible-project - for user questions, tips, and tricks
• https://groups.google.com/forum/#!forum/ansible-devel - for strategy, future planning, and questions about writing code

Because this project is very active, we're unlikely to see comments made on closed tickets, but the mailing list is a great way to ask questions, or post if you don't think this particular issue is resolved.

Thank you!

[kamranayub]

@jimi-c New to ansible here.

I was looking for this because I saw a module I wanted to use and it said to put it in ./library, so I went hunting in the docs to find a reference to this feature. So far, I still haven't found it.

This was the first page I read: http://docs.ansible.com/ansible/dev_guide/developing_modules.html

In it, it says explicitly:

Modules can be written in any language and are found in the path specified by ANSIBLE_LIBRARY or the --module-path command line option or in the library section of the Ansible configuration file.

No mention of relative library path. Your comment mentions the section "Module Paths", but that also doesn't have it: http://docs.ansible.com/ansible/dev_guide/developing_modules_best_practices.html#module-paths

If you are having trouble getting your module “found” by ansible, be sure it is in the ANSIBLE_LIBRARY environment variable.

If you have a fork of one of the ansible module projects, do something like this:

ANSIBLE_LIBRARY=~/ansible-modules-core

And this will make the items in your fork be loaded ahead of what ships with Ansible. Just be sure to make sure you’re not reporting bugs on versions from your fork!

To be safe, if you’re working on a variant on something in Ansible’s normal distribution, it’s not a bad idea to give it a new name while you are working on it, to be sure you know you’re pulling your version.

So the long and short of it is, at least since this issue was closed, it doesn't exist or isn't easy to find and searching Google brought me to this issue. Can we re-open?

[gundalow]

#24980 has some suggestions for improving the wording. Reviews welcome. Thanks in advance.

[thanatos]

So, I stumbled on this bug by Googling "where do I put custom ansible modules" or something similar, because I couldn't find it in the docs, so I have to disagree with this bug being closed.

there is a mention of the ./library path in the developing modules doc

That page never mentions "library" in the context of being a particular directory. (The word library appears literally, but not in that manner.)

[kamranayub]

Hi Roy, I agree with you which is why I have an open PR to improve the docs for this. It is still in progress.

…

On Thu, Jul 13, 2017, 18:16 Roy Wellington Ⅳ ***@***.***> wrote: So, I stumbled on this bug by Googling "where do I put custom ansible modules" or something similar, *because I couldn't find it in the docs*, so I have to disagree with this bug being closed. there is a mention of the ./library path in the developing modules doc That page never mentions "library" in the context of being a particular directory. (The word library appears literally, but not in that manner.) — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#7633 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAiaaymqzoTtIJihU1xgG0YFeRrSgkKdks5sNqU2gaJpZM4CAJQA> .