Provide HTML, HTML.zip and PDF version of documentation (retro, stable, latest)

[vlcinsky]

For offline work (e.g. in a train, at the aeroplane etc.) it is convenient to have project documentation at hand. We shall provide HTML version (for on-line access), HTML.zip (for download, unzip, study) and PDF (offline read).

The PDF may be skipped if it makes too much troubles, but personally I like this format for initial study as it has linear structure and is easy to get through. HTML is more hyperlinked document for jumping all around.

Versions which we shall provide are:

• stable (released version): can be created manually and uploaded somewhere (this would be probably default doc to provide)
• latest: built from latest source code: great, if it is published but if it makes troubles, we can skip it
• latest stable version compatible with Python 2.x: it can be made manually and uploaded somewhere. We can call it "retro". It shall serve for those, who are still living in 2.x Python.

[Kwpolska]

PDF shouldn’t be too hard, just install TeXLive (the most basic setup should do it) and run Sphinx with the correct options.

[vlcinsky]

@Kwpolska I agree, PDF works well. On Linux it requires some packages to install (rather lot of data to download, I guess around 800 MB, mostly fonts), but it works.

On next version (what we call "next version documentation teaser" as currently published on http://docs-next.pydoit.org/) it works with PDF very well, I locally use PlantUML to draw some activity diagrams making some sections more explanatory.

If we have problems to generate PDF automatically, we can skip it for the latest version and publish it after releasing new version what is not so often.

[saimn]

For offline usage something like dash or zeal works well (it easy to do, running doc2dash on Sphinx's output, and submit to https://github.com/Kapeli/Dash-User-Contributions). PDF is useless imho.

[vlcinsky]

@saimn I am using zeal too and consider it great tool for accessing any reference documentation.

For initial study of the documentation I do not like it so much as it seems really optimized for accessing structured reference material.

Regarding PDF, I used to hate reading doc in this format until I found Zathura which allows reading PDF in vim-like style: jump up, down, page jumping, text search there and back, tab opens table of contents (if the doc is generated in proper structured way).

Regarding Zeal/Dash doc, I like that idea anyway and will create separate issue for that.

[slippycheeze]

@vlcinsky, rather than create another issue, I'd ask this here as it is still open:

Would you also be willing to generate texinfo / info format manuals? The process is fairly simple with sphinx:

sphinx-build -b texinfo ...
cd build/texinfo  # or whatever output dir
makeinfo --no-split -o <docname>.info <docname>.texi

Then ship the .info file, and any images that are embedded in the documentation, as a single bundle.