Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Pull documentation of ansible.module_utils from its doc strings. #48416

Merged

Conversation

@aknrdureegaesr
Copy link
Contributor

@aknrdureegaesr aknrdureegaesr commented Nov 9, 2018

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
Copy link
Contributor

@ansibot ansibot commented Nov 9, 2018

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

click here for bot help

@ansibot
Copy link
Contributor

@ansibot ansibot commented Nov 9, 2018

@ansibot

This comment has been hidden.

@aknrdureegaesr
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Nov 9, 2018

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 456df7000024be4fbaba289f20492200056561b6, fixes that.)

@aknrdureegaesr aknrdureegaesr force-pushed the aknrdureegaesr:improve_module_utils_documentation branch Nov 9, 2018
@ansibot

This comment has been hidden.

@aknrdureegaesr aknrdureegaesr force-pushed the aknrdureegaesr:improve_module_utils_documentation branch Nov 10, 2018
@aknrdureegaesr
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Nov 14, 2018

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.

@aknrdureegaesr aknrdureegaesr force-pushed the aknrdureegaesr:improve_module_utils_documentation branch to dbc0d1b Nov 14, 2018
@mattclay mattclay requested a review from acozine Nov 16, 2018
@ansibot ansibot added core_review and removed needs_revision labels Nov 16, 2018
Copy link
Contributor

@gundalow gundalow left a comment

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

# not those may happen to be installed in the version of Python used to run sphinx.
# As sphinx loads in order to document, the repository version needs to be loaded:
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', '..', 'lib')))

VERSION = '2.7'

This comment has been minimized.

@gundalow

gundalow Nov 16, 2018
Contributor

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

This comment has been minimized.

@acozine

acozine Nov 16, 2018
Contributor

@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 . . .

This comment has been minimized.

@aknrdureegaesr

aknrdureegaesr Nov 17, 2018
Author Contributor

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.

This comment has been minimized.

@aknrdureegaesr

aknrdureegaesr Nov 17, 2018
Author Contributor

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
$

This comment has been minimized.

@acozine

acozine Nov 20, 2018
Contributor

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

This functionality is available via ``import ansible.module_utils.basic``:

.. automodule:: ansible.module_utils.basic
:members:

This comment has been minimized.

@gundalow

gundalow Nov 16, 2018
Contributor

What does members limit this to?

This comment has been minimized.

@aknrdureegaesr

aknrdureegaesr Nov 17, 2018
Author Contributor

"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
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Nov 20, 2018

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

@acozine
Copy link
Contributor

@acozine acozine commented Nov 20, 2018

@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
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Nov 25, 2018

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

@ansibot ansibot added the stale_ci label Nov 25, 2018
@acozine
Copy link
Contributor

@acozine acozine commented Nov 27, 2018

@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!

@acozine acozine added this to To do in Ansible Documentation via automation Nov 27, 2018
@aknrdureegaesr
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Dec 4, 2018

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

@ansibot
Copy link
Contributor

@ansibot ansibot commented Dec 4, 2018

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
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Dec 5, 2018

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
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Dec 6, 2018

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

@ansibot ansibot added core_review and removed needs_revision labels Dec 6, 2018
…strings.
@aknrdureegaesr aknrdureegaesr force-pushed the aknrdureegaesr:improve_module_utils_documentation branch to a947785 Dec 7, 2018
@aknrdureegaesr
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Dec 7, 2018

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

@ansibot ansibot added needs_revision and removed core_review labels Dec 7, 2018
@aknrdureegaesr
Copy link
Contributor Author

@aknrdureegaesr aknrdureegaesr commented Dec 9, 2018

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
Copy link
Contributor

@gundalow gundalow commented Dec 10, 2018

@aknrdureegaesr It worked, label was removed.

@acozine acozine merged commit 18bf48c into ansible:devel Dec 10, 2018
1 check passed
1 check passed
Shippable Run 97251 status is SUCCESS.
Details
kbreit added a commit to kbreit/ansible that referenced this pull request Jan 11, 2019
@acozine acozine moved this from To do to Done in Ansible Documentation Mar 7, 2019
@ansible ansible locked and limited conversation to collaborators Jul 22, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants