Pull documentation of ansible.module_utils from its doc strings.

[aknrdureegaesr]

SUMMARY

I find the current module_utils - documentation not very helpful.

The source code itself contains better documentation (even though not perfect).

This pull request activates the documentation from the source code for docs.ansible.com
and improves on that documentation somewhat, in particular, so that the tests pass.

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

module_utils

[ansibot]

Hi @aknrdureegaesr, thank you for submitting this pull-request!

click here for bot help

[ansibot]

cc @acozine
click here for bot help

[ansibot]

The test ansible-test sanity --test docs-build [explain] failed with 5 errors:

docs/docsite/rst/index.rst:0:0: unknown: /root/ansible/lib/ansible/module_utils/basic.py:docstring of ansible.module_utils.basic.AnsibleModule.get_bin_path:3: WARNING: Unexpected indentation.
docs/docsite/rst/index.rst:0:0: unknown: /root/ansible/lib/ansible/module_utils/basic.py:docstring of ansible.module_utils.basic.AnsibleModule.get_bin_path:5: WARNING: Block quote ends without a blank line; unexpected unindent.
docs/docsite/rst/index.rst:0:0: unknown: /root/ansible/lib/ansible/module_utils/basic.py:docstring of ansible.module_utils.basic.AnsibleModule.is_executable:6: WARNING: Unexpected indentation.
docs/docsite/rst/index.rst:0:0: unknown: /root/ansible/lib/ansible/module_utils/basic.py:docstring of ansible.module_utils.basic.AnsibleModule:1: WARNING: duplicate object description of ansible.module_utils.basic.AnsibleModule, other instance in /root/ansible/docs/docsite/rst/api/index.rst, use :noindex: for one of them
docs/docsite/rst/index.rst:0:0: unknown: /root/ansible/lib/ansible/module_utils/basic.py:docstring of ansible.module_utils.basic.human_to_bytes:3: WARNING: Unexpected indentation.

The test ansible-test sanity --test rstcheck [explain] failed with 1 error:

docs/docsite/rst/reference_appendices/module_utils.rst:17:0: Unknown directive type "autoclass".

click here for bot help

[aknrdureegaesr]

Interestingly, the present pull request is actually building the documentation for the module_utils that's installed in the load path of the python that's being used to run the build, not (as was intended) the module_utils of the ansible that's being build.

(For the record: The new version of this pull request, commit 456df70, fixes that.)

[ansibot]

The test ansible-test sanity --test docs-build [explain] failed with 1 error:

docs/docsite/rst/index.rst:0:0: unknown: /root/ansible/lib/ansible/module_utils/basic.py:docstring of ansible.module_utils.basic.AnsibleModule:1: WARNING: duplicate object description of ansible.module_utils.basic.AnsibleModule, other instance in /root/ansible/docs/docsite/rst/api/index.rst, use :noindex: for one of them

click here for bot help

[aknrdureegaesr]

The test passes my change on centos 6 but fails it on centos 7. I find this suspicious, as the change itself is documentation-only, so it should not be platform - dependent. Probing into the centos 7 failure, I find (slightly edited for readability):

https://download.fedoraproject.org/pub/epel/7/x86_64/repodata/721a6ec0aacec22adcb969c3e421a19ab4805ade557b2e6a6cda3c73ab0253c0-updateinfo.xml.bz2: [Errno 14] HTTP Error 302 - Found
Trying other mirror.
One of the configured repositories failed (EPEL yum repo),
and yum doesn't have enough cached data to continue. At this point the only
safe thing yum can do is fail. ...\n\n 

So I presume a flaky test environment. To test this assumption, I'll re-trigger the build by simply re-basing, without any further change, and see what happens.

[gundalow]

Nice PR. We can look at doing similar for other parts of the code base in the future.

[gundalow]

Interesting, would expect this to be 2.8 on devel, perhaps it isn't used by anything.

[acozine]

@gundalow I'm not sure what that does - I updated it (from 2.6) as part of the 2.7 release, thinking perhaps the VERSION setting in the Sphinx config should match the latest setting on the docsite. We could experiment . . .

[aknrdureegaesr]

I'm in the same boat with you regarding the "not being sure".

So I left this alone. I think it is not needed for the purpose of this pull request.

[aknrdureegaesr]

Being curious, I did an experiment, namenly, setting this VERSION to 3.14, then running make clean && make webdocs and greping all files for 3.14. Lessons learned:

"3.14" was not a good choice, as many tests contain an IP 11.12.13.14.

Every single .html - file generated contains a piece of javascript like this:

    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:'./',
        VERSION:'3.14',
        COLLAPSE_INDEX:false,
        FILE_SUFFIX:'.html',
        HAS_SOURCE:  false
      };
    </script>

, checked by

$ for f in $(find docs/docsite/_build/html -name \*.html); do grep -q "VERSION:'3.14'" $f || echo $f; done
$

[acozine]

Thanks for running the experiment, @aknrdureegaesr. I'll open a separate PR to update the version to 2.8 on devel.

[gundalow]

What does members limit this to?

[aknrdureegaesr]

"Limit" does not describe it very well... Just saying automodule:: just gives the doc string of the module itself. I considered it useful to also have the documentation of the module's members, so I added :members:. The sphinx doc explains this.

[aknrdureegaesr]

I don't think you are waiting for anything I should do, or are you?

[acozine]

@aknrdureegaesr we're not waiting on you, no - we might discuss this PR at the docs working group meeting today - starts in five minutes on the #ansible-docs channel on Freenode IRC.

[aknrdureegaesr]

In not-so-important news, this PR ended up not being discussed in the meeting.

[acozine]

@aknrdureegaesr very true, would you like to add it properly to next week's agenda? If you can join us, to answer any questions and speak up for your PR, that would be even better!

[aknrdureegaesr]

@acozine would it be possible to have this built on the test docs server?

I like having the docs built from the Python source.

For the record: In your local machine, in the top-level ansible directory, make clean && make webdocs generates the documentation in docs/docsite/_build/html. (You probably knew that, but just for the record.)

[aknrdureegaesr]

At this point in time, the result of 48e8c74 is (temporarily) available on my server.

[ansibot]

The test ansible-test sanity --test pep8 [explain] failed with 1 error:

lib/ansible/module_utils/common/file.py:33:1: E302 expected 2 blank lines, found 1

click here for bot help

[aknrdureegaesr]

Blocked by broken build

My current plan:

• Wait until bug #49541 has been resolved.

• Trigger another rebuild of this, by doing a rebase to wherever devel then is.

• Assuming the build succeeds, inform people at freenode's #ansible-doc that this can be picked up again.

[aknrdureegaesr]

Ready for merge!

The test status has turned to "All checks have passed" without my doing anything. Fine. In my opinion, this thing can and should now be merged into devel. This was agreed upon in the ansible-docs-meeting day before yesterday.

ready_for_review

[aknrdureegaesr]

I did happen to see an opportunity for improved language in one comment, which I acted upon.

[aknrdureegaesr]

A build had been red (undeservedly), we "fixed" that be rerunning without change until green (thank you, @gundalow !), so now it should all be ready for @acozine (or someone else) to have a look and merge. But somehow, this still has a label "needs_revision". I try to remove this label by:

ready_for_review

Later remark: Doesn't work. Apparently, as a mere contributor, I do not have the power to clean up wrong labels (which comes at no surprise).

[gundalow]

@aknrdureegaesr It worked, label was removed.