ansible-documentation
ansible-documentation copied to clipboard
ansible
Pdf/Epub/Offline documentation is missing
it is still a big problem not having the possibility to download an offline version of the manual. you are in a datacenter, no mobile internet available, all lan sockets are mac locked and require a certificate. you have to quickly lookup something for ansible. no way. this is very bad DX.
We do not produce documentation in pdf format at this time mainly because ansible is changing and updating all the time and we don't want to be passing obsolete documentation around to users.
this argument, which i found in an old issue, is simply wrong as exactly this has happend/is happening: people build a pdf version of the manual one time and put it out in the wild. those old builds ARE outdated. so denying us an official pdf which is build and updated on deploy of the doc webpage only leads to outdated pdfs.
please reconsider the wont-fix. don't lock the issues down, shutting down feedback does not solve the problem.
https://github.com/ansible/ansible/issues/9945 https://github.com/ansible/ansible/issues/4265
Files identified in the description: None
If these files are incorrect, please update the component name section of the description or use the !component bot command.
@c33s: Greetings! Thanks for taking the time to open this issue. In order for the community to handle your issue effectively, we need a bit more information.
Here are the items we could not find in your description:
- component name
- ansible version
Please set the description of this issue with an appropriate template from: https://github.com/ansible/ansible/tree/devel/.github/ISSUE_TEMPLATE
note: the issues are locked down to avoid you giving feedback to the ether, we don't get notified for old closed issues
Also. the ansible/ansible repo does not build ANY documentation sites, it only provides ansible-doc and man pages
@c33s This issue is waiting for you to provide the requested data in the description. Please edit the description or the issue will be closed.
bot_broken
note: the issues are locked down to avoid you giving feedback to the ether, we don't get notified for old closed issues
is it a bad thing to give feedback there if the described issue is still there? ansible/ansible#4265 has a lot of comments, to allow to comment there helps to get traction again. all the people commented there are also interested in the feature, are subscribed to the issue and would want a notification if something happens on this issue. with my new issue they don't even know that there is a chance to get this feature/there is a current discussion about it. it is rather uncommon to watch the whole repo if the repo has a lot of traffic. it is more common to watch a single issue you are interested in. in locking them down you only make people give up.
Also. the ansible/ansible repo does not build ANY documentation sites, it only provides ansible-doc and man pages
sorry my fault, can you direct me to the correct location? looks like https://github.com/ansible/docsite and https://github.com/ansible/community-docs is not the right direction. as far is i can see there is no public docs repo, is there?
It's now https://github.com/ansible/ansible-documentation. I'm going to move this issue there.
One of the problems we've talked about in the past is how fast the ansible documentation moves, and how a PDF would be stale pretty quickly. That said, there is a lot 'afoot' . One thing that's happening is all the Ansible projects are moving to Read the Docs, which has a PDF/epub option 'built in'.
Due to the complexity of the Ansible 'package' build (aka core and all the collections), that won't move over anytime soon. But core docs (most of the guides) will be on read the docs in the future and thus have epub/pdf options.
@c33s - does that match your need?
which has a PDF/epub option 'built in'.
It's just calling the corresponding built-in Sphinx builder. That builder still has to be configured properly in conf.py IIRC.
Thanks @webknjaz ...good to know
It's still a bit before we can get core docs on ReadTheDocs but it's definitely in the works and our goal is to have PDFs available shortly after that as well.
You'll need to run build twice, with https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder (or https://github.com/brechtm/rinohtype) the second time.
Has anyone tried running that with the ansible-core or ansible docs? I'm wondering how the module/plugin docs look in the result. My guess is that they should be ok as we don't use HTML blobs anymore, and the LaTeX builders hopefully simply ignores the raw HTML insertions (which are mainly needed for permalinks and reponsive layout. I guess that some formatting would be missing though, as we probably would have to supply specific styling information for the roles that the antsibull sphinx extension provides and antsibull-docs uses. (I have never looked into how this can be done for LaTeX output, maybe it's easy, maybe not at all.)
@samccann An issue with the Read The Docs approach right now is that we need to call the makefile to build coredocs instead of using the RTD sphinx build which can do the latex / pdf build. I think if we can create the separate folder structure with a conf.py it might be possible to get RTD to build the pdf. I don't want to put more of that in the makefile tbh.
we need to call the makefile to build coredocs instead of using the RTD sphinx
This is easily solvable by putting that invocation inside a setup() function in conf.py or a full-blown extension module (also in-tree).
RTD sphinx build which can do the latex / pdf build
With the commands replacement capabilities, you can call whatever you want, by the way, like you do in the jinja docsite repo. It completely replaces RTD's invocations.
I think if we can create the separate folder structure with a
conf.pyit might be possible to get RTD to build the pdf.
Honestly, I've been meaning to merge those conf files long ago. It should be possible to make use of conditionals controlled via CLI args w/o the need to copy/move files around.
RTD sphinx build which can do the latex / pdf build
With the commands replacement capabilities, you can call whatever you want, by the way, like you do in the jinja docsite repo. It completely replaces RTD's invocations.
Yep but this means you also don't get some of the RTD bells and whistles out of the box, iirc. For the actual docs I would prefer to use the default RTD builders where possible for that reason.
Honestly, I've been meaning to merge those conf files long ago. It should be possible to make use of conditionals controlled via CLI args w/o the need to copy/move files around.
That could work but wouldn't conditionals risk increasing complexity where separating the conf files could fully decouple core and package docs for more modular builds, even if it means having an additional conf file that might be redundant in some places?
Yep but this means you also don't get some of the RTD bells and whistles out of the box
You can get those by copying the pip installs it does by default.
For the actual docs I would prefer to use the default RTD builders where possible for that reason.
There's no "RTD builders", it uses the default Sphinx builders which is what is being suggested anyway.
That could work but wouldn't conditionals risk increasing complexity where separating the conf files could fully decouple core and package docs for more modular builds, even if it means having an additional conf file that might be redundant in some places?
It should make things much simpler. It's quite a mess, currently.
thank you all for you effort to make this happen!
One of the problems we've talked about in the past is how fast the ansible documentation moves, and how a PDF would be stale pretty quickly.
as i can say from my search for a pdf, not building official pdfs just lead to more stale and more older pdfs as people build the pdfs themself one time and upload it somewhere. most pdfs i found where totally outdated.
One thing that's happening is all the Ansible projects are moving to Read the Docs, which has a PDF/epub option 'built in'.
thats good to hear <3
Due to the complexity of the Ansible 'package' build (aka core and all the collections), that won't move over anytime soon. But core docs (most of the guides) will be on read the docs in the future and thus have epub/pdf options. does that match your need?
yes, having an epub and a pdf file with a current manual matches my need. i don't care of i download it from github, ansible.com or RTD.
maybe someone could post this issue in the related issues, so the people know this topic got traction again.
- https://github.com/ansible/ansible/issues/9945
- https://github.com/ansible/ansible/issues/4265
I tried out rendering some collection docs as PDF.
-
https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder: looks generally good, but tables have to fit on one page, otherwise they are cut off (except if there are at least 30 rows, apparently, then a long table is used). Also in attribute tables, the first column is usually too narrow and text is cut off. Fortunately there is a workaround; I'll create a PR for antsibull-docs shortly. The main disadvantage of this workaround is that all column take the same amount of space, which leads to a rather empty left column (i.e. lots of whitespace) and a densly filled right column. There is another way to fix this though (https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-tabularcolumns), unfortunately not in a dynamic way (since the longtable LaTeX package does not support that). So some fixed ratios have to work for everything.
One thing that also does not work (and is harder to fix) are nested options/return values. For the HTML version, the nesting is achieved by adding some raw HTML and by adding a CSS stylesheet. The main problem is that Sphinx only allows to join cells in grid tables, which is a format we likely don't want to use. We currently use list tables, which do not support joining. Maybe this can be worked around by also adding raw LaTeX code (
.. raw:: latex). I'll try that out maybe later. -
https://github.com/brechtm/rinohtype: Works much better with tables. Table content is vertically centered by default, though, which is pretty weird for the left column in option and return value tables. Obviously has the same problems with nested options/return values.
Using both renderers, both the collection links section (whose content is pure HTML) is empty and nested options and return values do not work. Supporting the links section is definitely possible, but requires some work (and extra CSS).
Supporting nested options and return values is a lot more tricky. Even if we could join cells (which is what the original HTML table generator was doing), we still have the problem of not being able to use a responsive design (or at least not without some novel ideas on how to do this) for HTML output. Without joining cells, we have to resort to hacks, like inserting raw HTML and LaTeX - which will not work (that easily) with rinoh.
What's also not supported is styling, like the colors and smaller font sizes we use for things like the option type, required marker, version added, etc. While it is possible to solve this by creating our own node types (https://stackoverflow.com/a/70717174), I guess one could also insert "raw" nodes for LaTeX to add formatting. I might try this out later.
One thing that's easier to have than fully working PDFs are offline HTML docs. Maybe providing a docset for Dash/Zeal would be helpful as well (https://hynek.me/articles/productive-fruit-fly-programmer/, https://github.com/zealdocs/zeal). Not sure how well EPUB will work (I won't try it out for now), it might have its own bag of problems, especially with regard to styling and rendering tables. Without ever having tried them, Dash/Zeal sound like a better solution to me than EPUB or PDF.
I created https://github.com/ansible-community/antsibull-docs/issues/196 to track the work needed to improve support for Sphinx's LaTeX builder.
I managed to adjust antsibull-docs so that the PDF output is pretty usable. The biggest problems (cut-off tables, missing indent for nested options/return values) are fixed, at least for the 'general' case (if you use extreme nesting, say deeper than 10 levels, it gets tight, and more than 15 levels result in zero or negative widths).