LaTex, Texinfo and Man pages downloads options

[doronbehar]

Question:

In sphinx website's front page, it is stated that it has the capability to export the documentation in formats like LaTex, Texinfo and Man pages.
I was wondering what is holding the documentations hosted on https://readthedocs.org from having in the downloads page (like this: https://readthedocs.org/projects/beets/downloads/).

Thanks.

[stsewd]

I don't think that kind of formats will be useful for the final user, I mean the download options are for offline reading and most common is reading in pdf or ePub

[doronbehar]

Very often I find my self in need of offline documentation of some software with internal links for navigating between the documentation's nodes. I find Texinfo to be the best format for this since it is also available when no X display is running, the same with Man pages.
I understand that on a documentation's website it may bring unnecessary clutter to the side menu but perhaps it may be useful to put it in the project's downloads page under the main domain - https://readthedocs.org/projects/{project}/downloads/.

[agjohnson]

Hrm, interesting proposal, but I'd probably be -1 just because I don't think these formats are generally useful for others. Read the Docs focuses on more useable formats -- html, pdf, and epub are all easily viewable. Man pages are a strange thing to distribute as one off files, latex is not easily humanly readable, and i don't know much about texinfo but I know it's somewhat synonymous with latex and is used as an intermediary to more useable formats.

Maybe there are other builders that we should be supporting though? However, if the builder output can be easily supported, perhaps there is not much stopping us from offering these formats as additional formats.

[doronbehar]

Texinfo is much more superior then man pages or LaTeX since it is converted into .info files which can be used to read the documentation on a terminal. Try to run on your command line info info and learn about it.

The default info viewer on GNU systems is capable of jumping between nodes just like jumping between internal links in a documentation website. That's what makes it so useful for offline reading without dependence on Xorg.

.info documentation is distributed along with every GNU software on the GNU/Linux OS. Imagine that every software that doesn't maintain documentation in that format but only through rtfd, could now easily distribute documentation in this format as well.

[slippycheeze]

For what it is worth, I'd certainly appreciate being able to obtain the .info format of documentation more easily than I can today -- which involves figuring out for each project the documentation build process, then running sphinx-build -b texinfo ... to generate the intermediate source appropriately.

Turning that into the final info format is equally simple:

$ makeinfo --no-split -o <docname>.info <docname>.texi

The makeinfo tool is available in the package makeinfo for Debian. The version shipped with stable should be more than sufficient for the purpose.

Note: using sphinx-build in "make mode" offers an info target that handles running makeinfo(1) automatically. It literally does what is noted above. :)

You then need to put the single .info file, and any images, into a zip file or whatever, and the job is done. (Technically, the images are not required, as the alternate textual description is also included, but it would be considerate.)

I do recognise that this is a more niche format than some, but it also has significant advantages when used with Emacs -- indexing, and automatic lookup of symbols from source code, for example, that don't have the same integration when viewing HTML or equivalent documentation.

The runtime cost of building the Python3 documentation in full to this format was ~ 17 CPU-seconds on a 2.2 GHz Intel Core i7 from mid 2015. Most documentation isn't going to generate the same ~ 7MB that contains, so should be substantially faster to build.

If you would accept the feature, but not the time investment to build it, I'd be happy to see about getting a pull request to you adding it? No promises, but it seems like a better investment of my time than doing the same thing purely for myself.

edit to add: I have less than zero interest in manpage output, myself. .info yes, but that is all.

[humitos]

As it was mentioned before, Read the Docs is not going to build this feature on its core functionality.

However, with the introduction of build customization (https://docs.readthedocs.io/en/latest/build-customization.html) users are allowed execute customized commands. Projects requiring these files, the generation of LaTex, TexInfo and Man pages can be achieved with that feature and saved into $READTHEDOCS_OUTPUT/html to be served.

version: 2
build:
  os: ubuntu-22.04
  jobs:
    post_build:
      - sphinx-build -b textinfo ...