rewrite of the developer guide, part 1 #45179
Conversation
ansibot
added
affects_2.8
docs/docsite/rst/dev_guide/index.rst
Outdated
|
|
||
| To get started, select one of the following topics. | ||
| If you want to extend Ansible by using a non-core module or plugin locally, creating a module or plugin, adding functionality to an existing module, or expanding test coverage, this guide is for you. We've included detailed information for developers on how to test and document modules, as well as the pre-requisites for getting your module or plugin accepted into Ansible Core. |
There was a problem hiding this comment.
prerequisites
Also, is this really only applicable to Ansible Core?
| .. _debugging: | ||
|
|
||
| ================= | ||
| Debugging Modules |
There was a problem hiding this comment.
Is this a good opportunity to start using sentence case (ccs standard approach)?
There was a problem hiding this comment.
Sigh. I suppose you're right.
|
|
||
| To debug a module running on a remote target (i.e. not ``localhost``): | ||
|
|
||
| - On your controller machine (running Ansible) set ``ANSIBLE_KEEP_REMOTE_FILES=1`` (this tells Ansible to retain the modules it sends to the remote machine instead of removing them) |
There was a problem hiding this comment.
all of these items need a period at the end :-) This would ideally be a numbered list as well (tho I wish rst automatically numbered!)
There was a problem hiding this comment.
Hey, it turns out rST does support automatically numbered lists. Instead of 1. and 2., you put #. I tested this on a single page and am going back now to implement this across the dev guide. See https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#list-and-bullets.
There was a problem hiding this comment.
does it render on github? iirc that is main reason people stuck to 'direct numbering'
| - Take note of the remote path Ansible used on the remote host | ||
| - SSH into the remote target after the completion of the playbook | ||
| - Navigate to the directory (most likely it is going to be your ansible remote user defined or implied from the playbook: ``~/.ansible/tmp/ansible-tmp-...``) | ||
| - Here you should see the module that you executed from your Ansible controller, but this is the zipped file that Ansible sent to the remote host. You can run this by specifying ``python my_test_module.py`` (not necessary) |
There was a problem hiding this comment.
You can optinally run this by...
... and then remove the (not necessary) from the end of this item
| Extending Ansible with local modules and plugins offers lots of shortcuts: | ||
|
|
||
| * you can copy other people's modules and plugins | ||
| * if you're writing a new module, you can choose any programming language you like |
There was a problem hiding this comment.
In theory, these should all start with a capital and end w/ a period.
|
|
||
| To check the HTML output of your module documentation: | ||
|
|
||
| * save your completed module file into the correct directory: ``lib/ansible/modules/$CATEGORY/my_code.py`` |
There was a problem hiding this comment.
Should be capital and end in period... and ideally numbered.
acozine
force-pushed
the
dev_guide_short
branch
from
3f07f51
to
57de1e7
Compare
acozine
force-pushed
the
dev_guide_short
branch
from
57de1e7
to
380d5a7
Compare
* rewrite of the developer guide, part 1 (cherry picked from commit 9a76441)
(cherry picked from commit 9a76441)
SUMMARY
Revision of the content in
docs/docsite/rst/dev_guide. The proposed revisions can be seen (temporarily) at http://docs.testing.ansible.com/ansible/latest/dev_guide/index.html. For comparison purposes, the current content is at https://docs.ansible.com/ansible/devel/dev_guide/index.html and related pages.This PR incorporates comments made on the first WIP PR, #44098.
ISSUE TYPE
COMPONENT NAME
docs.ansible.com/ansible/devel/dev_guide
ANSIBLE VERSION
2.7
ADDITIONAL INFORMATION
This changeset:
testing_legacy_integrationandrepomergepages and adds four new pages