-
Notifications
You must be signed in to change notification settings - Fork 24k
Pull documentation of ansible.module_utils from its doc strings. #48416
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
Conversation
Hi @aknrdureegaesr, thank you for submitting this pull-request! |
This comment has been minimized.
This comment has been minimized.
Interestingly, the present pull request is actually building the documentation for the (For the record: The new version of this pull request, commit 456df7000024be4fbaba289f20492200056561b6, fixes that.) |
d448aa4
to
456df70
Compare
This comment has been minimized.
This comment has been minimized.
456df70
to
2e84d84
Compare
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):
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. |
2e84d84
to
dbc0d1b
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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' |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Interesting, would expect this to be 2.8 on devel
, perhaps it isn't used by anything.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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 . . .
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Being curious, I did an experiment, namenly, setting this VERSION to 3.14
, then running make clean && make webdocs
and grep
ing 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
$
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What does members
limit this to?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"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.
I don't think you are waiting for anything I should do, or are you? |
@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. |
In not-so-important news, this PR ended up not being discussed in the meeting. |
@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 would it be possible to have this built on the test docs server? I like having the docs built from the Python source. It's then a lot easier for people to update the Python files with docs. I'll happily do this for module argspec |
dbc0d1b
to
48e8c74
Compare
At this point in time, the result of 48e8c74 is (temporarily) available on my server. |
The test
|
6a4958d
to
35a237f
Compare
Blocked by broken buildMy current plan:
|
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 |
35a237f
to
a947785
Compare
I did happen to see an opportunity for improved language in one comment, which I acted upon. |
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). |
@aknrdureegaesr It worked, label was removed. |
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
COMPONENT NAME
module_utils