Hello
Could someone please direct me towards the Ansible documentation PDF’s
I only seem to be able to find the online documentation but no PDF versions.
I have search in this forum but I can not find the answer.
Thank you
Stuart
Docs are available at docs.ansible.com, through the ansible-doc tool
and man pages, docs are maintained inside the main ansible repo and
within each module.
There is no official pdf provided, mostly because it is too static a
format and changes are constant as ansible continually grows.
Why does Ansible not provide documentation in PDF format?
Other software providers provide manage to provide PDF versions.
Red Hat manages to provide PDF versions of their documentation and the Linux OS is not static and certainly more complex than Ansible.
Oracle provides PDF versions of their products documentation.
CFEngine provides PDF versions of their product documentation.
The vast majority of software providers manage to provide PDF versions of their software products.
I can not think of any other software provider that does not provide PDF versions of documentation.
The Ansible Tower software has a PDF version of the documentation. That is not static.
I feel that the reason provided of “changes are constant” is not a real reason.
The online documentation is only available online and therefore somewhat limited.
The providing of PDF versions of documentation is really the professional thing to do.
Maybe it is worth having a re-think as to the reason why Ansible do not do this.
You may want to see the explanation at https://github.com/ansible/ansible/pull/8906#issuecomment-54889577
Thank you Mat
After reading the referenced post I feel that the reasoning why there are no PDF versions of the documentation is more of an excuse really rather than a justification.
There is certainly a case for online documentation.
There is also a case for PDF versions.
Everyone else manages to provide PDF versions and really it is the professional thing to do.
Other organisations manage to provide PDF versions for operating systems. This is an application. It is far less complex than an OS.
All software changes. To not provide adequate documentation and use the fact that there are ongoing changes is not really very good in my opinion.
Disclaimer: I have no associattion with the Ansible org other than
being a user of their application.
Everyone else manages to provide PDF versions and really it is the
professional thing to do.
The three examples you gave earlier (Redhat, Oracle, CFEngine) of
"everyone" that provides PDF documentation are all vastly larger
organizations with many, many more resources to throw at documentation
than Ansible has. Ansible has limited resources to deal with this sort
of thing and they've chosen to stick with a single "authoritative"
documentation source.
Other organisations manage to provide PDF versions for operating systems.
This is an application. It is far less complex than an OS.
Yes indeed, far less complex. But complexity isn't the problem - rate
of change is the problem. I'm not certain how often Ansible
re-generates their documentation, but it may be as often as with each
merged pull request. For Redhat, the rate of change is *very* slow.
They probably re-generate their documentation once a quarter or less.
All software changes. To not provide adequate documentation and use the fact
that there are ongoing changes is not really very good in my opinion.
Ansible *does* provide very adequate documentation - some of the best
in the industry. Accusing them of not providing adequate documentation
seems a bit disingenuous. Their documentation is just not in your
preferred format. That's OK. My preference is to have html
documentation. I suspect the vast majority of Ansible users feel the
same way, which is another reason why the documentation is in that
format.
You're always free to take the RST sources[1] and generate PDF docs
for yourself. Heck, you can even take the work done by Matt in pull
request 8906 that he linked to earlier, and use that as your starting
point.
-ea
[1] https://github.com/ansible/ansible/tree/devel/docsite/rst
Personally I find Michael's explanation very reasonable, but admittedly I
have absolutely no use for PDF documentation. I'm certainly not going to
print it out.
If your motivation is to have offline documentation, why not simply build
it yourself? (see the Makefile)
Thank you for the replies.
I think that the lack of PDF documentation is a bit disappointing and lets does a good product.
I can not really recommend the client goes with this product and then has to produce their own offline PDF documents. I do not think that the idea will fly at all well, especially when they are paying for the product.
Thanks for the replies though.
Ansible evolves quickly, and we want to encourage people to be looking at new versions, understaning the new features, and getting the latest corrections to the documentation. Often when looking at module documentation you’ll see a “new option added in 1.8” and say “Hey, I really need to consider 1.8” that you would not get exploring the 1.4 documentation – and as a result, we’d probably get a lot of bug tickets against an old release we are not maintaining too 
The documentation is also a great way to communicate with users that are not on this list, with things like Ansible Fest, being able to share things like Ansible Galaxy coming out, the preview of the O’Reilly book, and so on. These are very important things to us. Right now, the mailing list has about 4000 subscribers, but we have hundreds of thousands (if not more) Ansible users. The docs are our way of communicating with those folks.
If you need offline module documentation, you are welcome to use “ansible-doc” to read the module documentation, which can be used offline. “man ansible-doc” for details.
You can also build a snapshot of the HTML docs for local consumption on restricted networks by “make webdocs” from a source checkout after installing python-sphinx.
I do not think that the idea will fly at all well, especially when they are paying for the product.
And when they pay for it (Ansible Tower) they get a PDF … problem solved!
We generate the Tower docs via a different system - but yes, there is a PDF there.
Just so it’s clear that there isn’t any favoritism, Tower users don’t get any special PDF of ansible docs either, they are 100% the exact same docs
I actually haven’t looked into rst2pdf (which apparently supports Sphinx) – though I still think there’s a lot of value in getting the recent bits and viewing those, and I think if folks get snapshotted to a particular version of Ansible, that will eventually result in a degree of frustration.
(Particularly, as libraries change – API breaks in libraries we use do happen – folks need to stay up to date)