Unable to generate documentation #2
Comments
|
Can you pull it down again and re-try? I just pushed a fix for another Thanks, On Mon, Jul 27, 2015 at 6:00 AM, dheerajpanyam [email protected]
|
|
I pulled the latest version again and tried but still not generating the complete documentation. I have validated my custom module for the comments i added for the documentation using YAMLIint and it returned fine . Regards |
|
Can you post your module ? If you prefer not to post here, email it to me On Mon, Jul 27, 2015 at 8:24 AM, dheerajpanyam [email protected]
|
|
Below is the YAML portion of the module , following it is the actual python module code which is implemented in a OO fashion . #!/usr/bin/env python DOCUMENTATION = '''module: Vistara_Maintenance
EXAMPLES = ''' Schedule a 30 min Vistara Maintenenance window containing 2 devicegroups and 3 devices for client Netenrich Internal in the IST timezone from 3pm to 3:30pm
Schedule a 3hr 15min Vistara Maintenenance window for a desktop device in the Netenrich Internal domain from 6pm to 9:15pm
|
|
Can you please post it in a code block like so: This way, I can see the proper layout. |
|
Sorry i realised it later that it was rendering the YAML code i pasted into a markdown , how do i post it in a code block? Dheeraj |
|
Use the character to the right of the "1" on the keyboard, i.e. the backtick "`" like so: Three backticks: "```" without the quotes, the paste your code/yaml, and then close it with three more backticks. Also see this: https://help.github.com/articles/markdown-basics/#code-formatting |
|
Thanks , i am a newbie to git below is the YAML portion of the Ansible module |
|
Thanks , I pasted the code very much appreciate your quick responses and help. Dheeraj From: Jason Edelman [mailto:[email protected]] Use the character to the right of the "1" on the keyboard, i.e. the backtick "`" like so: Three backticks: "```" without the quotes, the paste your code/yaml, and then close it with three more backticks. Also see this: https://help.github.com/articles/markdown-basics/#code-formatting — Confidentiality And Disclaimer Notice Please do not print this email unless it is absolutely necessary. The |
|
That's odd, it seems to work for me...make sure you know where you are saving the correct file :) FooBarRequirements
ModulesVistara_MaintenanceSchedule a Vistara Maintenenance window
SynopsisSchedules a Vistara Maintenance window for a specific set of devices/Device Groups with a starttime and endtime in the specified timezone Options
ExamplesCreated by Network to Code, LLC |
|
I am using the default output directory specified in the playbook , I changed the module path to point to the location where my modules are present tasks: From: Jason Edelman [mailto:[email protected]] That's odd, it seems to work for me...make sure you know where you are saving the correct file :) Foo Requirements
Modules
Vistara_Maintenance Schedule a Vistara Maintenenance window
Synopsis Schedules a Vistara Maintenance window for a specific set of devices/Device Groups with a starttime and endtime in the specified timezone Options required default choices comments name no Created By Ansible Name for the maintenance start_time yes Specifies the start time for the maintenance window in the specified timezone devices false if devicegroups option is used Comma seperated list of devices to be put to maintenance, one of the parameters devices or devicegroups need to be given as input schedule_type yes
Describes the maintenance type devicegroups false if devices option is used Comma seperated list of device groups to be put to maintenance, one of the parameters devices or devicegroups need to be given as input end_time yes Specifies the end time for the maintenance window in the specified timezone client_id yes Specifies the tenant Id timezone yes [u'America/Los_Angeles'] Specifies the timezone for the maintenance window description no Describes what the maintenance is intended for Examples Schedule a 30 min Vistara Maintenenance window containing 2 devicegroups and 3 devices for client Netenrich Internal in the IST timezone from 3pm to 3:30pm
Schedule a 3hr 15min Vistara Maintenenance window for a desktop device in the Netenrich Internal domain from 6pm to 9:15pm
Created by Network to Code, LLC — Confidentiality And Disclaimer Notice Please do not print this email unless it is absolutely necessary. The |
|
Please change the dest path to be the absolute path, i.e. |
|
Yes I am using the absolute path and running this playbook on a vagrant Ubuntu 14.04. I am using Ansible 1.8.4 Regards From: Jason Edelman [mailto:[email protected]] Please change the dest path to be the absolute path, i.e. /home/foo/bar/ansible-webdocs/ansible-webdocs/web/ansiblefilesdoc.md — Confidentiality And Disclaimer Notice Please do not print this email unless it is absolutely necessary. The |
|
Hello Jason, Yes i changed the path to absolute path for the markdown task in the playbook , this is how it looks like tasks: |
|
Can you run the playbook in verbose mode with the |
|
Below is the playbook output run in verbose mode vagrant@vagrant-ubuntu-trusty-64:~/ansible-webdocs$ ansible-playbook create-ansible-webdoc.yml -i /home/vagrant/playbooks/inventory -v PLAY [create local markdown doc] ********************************************** TASK: [get docs and examples for modules] ************************************* TASK: [build web/markdown ansible docs] *************************************** PLAY RECAP ******************************************************************** vagrant@vagrant-ubuntu-trusty-64:~/ansible-webdocs$ |
|
I made a minor tweak. Please do a |
|
Hello Jason, However one important thing is that the generated markdown does not have any entry for my custom module. vagrant@vagrant-ubuntu-trusty-64:~/ansible-webdocs$ ansible-playbook create-ansible-webdoc.yml -i /home/vagrant/playbooks/inventory -v PLAY [create local markdown doc] ********************************************** TASK: [get docs and examples for modules] ************************************* TASK: [build web/markdown ansible docs] *************************************** FATAL: all hosts have already failed -- aborting PLAY RECAP ******************************************************************** localhost : ok=1 changed=0 unreachable=1 failed=0 |
|
Hello Jason, I pulled the git module and reran the playbook. The documentation is getting generated but it doesn’t have any entries related to my module, I made sure the path for the modules is correct and absolute in the playbook. Regards From: Jason Edelman [mailto:[email protected]] I made a minor tweak. Please do a git pull for the latest and try it again running with the -v set. — Confidentiality And Disclaimer Notice Please do not print this email unless it is absolutely necessary. The |
|
Did you get this working? If not, try and clean up your examples. If you're using the one-line notation, try not including colons Do something like what is below.. I also made another minor change to see if this helps (so please do another git pull), but based on what you are seeing, the problems are with your example syntax. You may want to try a really simple example like this: |
|
I remove the example section in my module and after re-syncing your git module I ran the playbook , the markdown is empty now Below is the markdown file which got generated Ansible FILES modulesLocal copy of files modulesRequirements
ModulesCreated by Network to Code, LLC Dheeraj From: Jason Edelman [mailto:[email protected]] Did you get this working? If not, try and clean up your examples. If you're using the one-line notation, try not including colons :. and wrap your long strings with quotes. Do something like what is below.. EXAMPLES = ''' Schedule a 30 min Vistara Maintenenance window containing 2 devicegroups and 3 devices for client Netenrich Internal in the IST timezone from 3pm to 3:30pm
''' I also made another minor change to see if this helps (so please do another git pull), but based on what you are seeing, the problems are with your example syntax. — Confidentiality And Disclaimer Notice Please do not print this email unless it is absolutely necessary. The |
|
Try not removing it, but include this: |
|
I tried but still same result , below is the EXAMPLES section I added EXAMPLES = ''' Schedule a 30 min Vistara Maintenance window containing 2 device groups and 3 devices for client Netenrich Internal in the IST time zone from 3pm to 330pm''' Regards From: Jason Edelman [mailto:[email protected]] Try not removing it, but include this: EXAMPLES = ''' Schedule a 30 min Vistara Maintenenance window
''' — Confidentiality And Disclaimer Notice Please do not print this email unless it is absolutely necessary. The |
|
This is strange b/c it's always worked for me. Can you try to upgrade Ansible? |
|
I had Ansible 1.8.4 and I upgraded to 1.9.2 and also emptied the EXAMPLES section. I am unable to run the playbook now vagrant@vagrant-ubuntu-trusty-64: From: Jason Edelman [mailto:[email protected]] This is strange b/c it's always worked for me. Can you try to upgrade Ansible? sudo pip install ansible --upgrade and empty example so example looks like this: EXAMPLES = ''' ''' — Confidentiality And Disclaimer Notice Please do not print this email unless it is absolutely necessary. The |
|
Are there any errors? Please send me the |
|
Please find below the verbose output of the playbook run after upgrading Ansible to 1.9.2 and also emptying the EXAMPLES section. Regards From: Dheeraj Panyam I had Ansible 1.8.4 and I upgraded to 1.9.2 and also emptied the EXAMPLES section. I am unable to run the playbook now vagrant@vagrant-ubuntu-trusty-64: From: Jason Edelman [mailto:[email protected]] This is strange b/c it's always worked for me. Can you try to upgrade Ansible? sudo pip install ansible --upgrade and empty example so example looks like this: EXAMPLES = ''' ''' — Confidentiality And Disclaimer Notice Please do not print this email unless it is absolutely necessary. The |
|
I know this is an old issue but I had the same problem and it took me a couple hours to figure out why my doc was not being generated. You need to be VERY VERY careful with your indentation. If you miss a white space or have an extra one, this will create a parse error (not thrown by Ansible or the module) and your doc won't be generated. Here are the two mistakes I did:
DOCUMENTATION = r'''
---
options:
login_port:
description:
- Port of the MySQL server.
'''each sub-level of DOCUMENTATION = r'''
---
author:
- Cesar Jeanroy
requirements:
- Requires the python-mysqldb package on the remote host
notes:
- Privileges can be specified using either upper or lower case.
- When using the module with verbose flag (-vvv).....
'''
DOCUMENTATION = r'''
---
options:
status:
description:
- If state: present then... <- This will cause an error
- If state=present then... <- This won't cause an error
'''That would be awesome if the module could tell where the parse failed. Anyway, Thanks for that really cool module! 👍 |
Hi ,
I am trying to generate the markdown for a custom module that i wrote, the module follows the Ansible standards in documentation and i do not suspect anything wrong here. It is creating a markdown with empty content ( just the header and the sub-header). The module path etc is set correctly in my playbook used to generate the markdown.
I am using ansible 1.8.4
Please help
vagrant@vagrant-ubuntu-trusty-64:~/ansible-webdocs/ansible-webdocs$ ansible-playbook create-ansible-webdoc.yml -i /home/vagrant/playbooks/inventory
PLAY [create local markdown doc] **********************************************
TASK: [get docs and examples for modules] *************************************
ok: [localhost]
TASK: [build web/markdown ansible docs] ***************************************
changed: [localhost]
PLAY RECAP ********************************************************************
localhost : ok=2 changed=1 unreachable=0 failed=0
vagrant@vagrant-ubuntu-trusty-64:
/ansible-webdocs/ansible-webdocs$ cd web//ansible-webdocs/ansible-webdocs/web$ vi ansiblefilesdoc.mdvagrant@vagrant-ubuntu-trusty-64:
vagrant@vagrant-ubuntu-trusty-64:~/ansible-webdocs/ansible-webdocs/web$
Below is the markdown that got generated
Ansible module for Vistara Maintenance
Schedule a Vistara Maintenance Window
Requirements
Modules
Created by Jason Edelman. February 2015.
The text was updated successfully, but these errors were encountered: