This is a bug and/or feature request

[SamtheTruck]

Describe the bug

I submit that the whole essence of your document project fails at the fundamental level. It sucks "unless" you want to be tethered to the internet. Is that your goal? If so, you've managed it perfectly. I see more and more projects using your software which looks wonderful, but it's a massive headache to download the whole of the documentation to single file where you can use it off-line. It's a huge step backwards in usability of documentation. You will of course resound that you can set it up to do so but...you don’t even do this on your own site and a very large amount of others do not do either.

This means that to actually see the documents, unless you are tethered to the net, you have use another set of software to try and copy the site and its links. This causes further trouble, as you now have to scroll through every link to see how deep you need to go to capture the documents you need. It’s a huge hairball and a text file would be far superior as you can download it easily and have all the information you need.

I can not help but see that this is a huge blinding example of Elon Musk adage that engineers will speed an enormous amount of time optimizing something that they don't need in the first place. Before your fabulous software, people would make a text file or a one page HTML file that was immediately useful. Now, worse is better. You have pages of wonderful features that are completely useless to someone who doesn’t want to be on the internet 24 hours a day to read docs.

But don’t feel bad, you are in good company. I have an iPhone and it’s a huge step backwards where it does everything in the world but to get it to do so you must learn hieroglyphics. Some of these icons mean??? well I don't know what they mean and there's no manual so, once again, if you are not tied to the internet and willing to scroll through tons of pages to find out, you can’t use any of these great features.

If it’s so easy to add a step to capture in one document the docs, then why don't you have this on your own doc page???

https://www.sphinx-doc.org/en/master/

My suggestion is to hard code it such that at the bottom of every document there's a link to a one page document that can be downloaded. Instead of it being an option, which very few people use for whatever reason, make it so it must be taken away. If they have reason to do so...fine, but documents should be able to be downloaded without such a large amount of effort. Most of the programs that these documents reference are on the person's computer, not the internet. Shouldn't the documents be the same place?

How to Reproduce

Look at your own site's documents and many, many others. They fail.

Environment Information

NA

Sphinx extensions

NA

Additional context

NA

[jayaddison]

Hi @SamtheTruck - one benefit of online documentation is that it can be edited and updated continuously, and for popular projects with widely distributed - and participatory - user communities, that can be much more effective than static local documentation. I'd agree that some amount of local/offline documentation can be useful too, though.

As you noticed already I think (based on your mention of options), documentation can be built with the singlehtml builder to provide a single-file result, and each documentation project can choose between that and the multi-file html builder. As the amount of content in a project becomes larger, the user experience in most HTML browsers is likely to be better with the multi-file approach -- and the bandwidth required for a typical reference session is likely to reduce.

Are there particular projects that you would like to see offer downloadable versions of their documentation? Some projects, such as Python, already offer this.

[picnixz]

By the way, you can directly download the PDF of the documentation if you click on "v:master". You'll get a single PDF file that you could look whenever you're offline.

Usually users host their doc on RTD which allows to download docs like that. Otherwise, you can always build the doc locally from the sources (usually, you just clone the repo, go to some doc folder and run make html).

[SamtheTruck]

jayaddison,"...documentation can be built with the singlehtml builder ..."

Aren't computers supposed to do this for us, "IF" you are suggesting I do this. Otherwise, much the same, why should this be an extra step.

You mentioned,"...As the amount of content in a project becomes larger, the user experience in most HTML browsers is likely to be better with the multi-file approach -- and the bandwidth required for a typical reference session is likely to reduce..."

First, if they do not want the whole document, they can just not download it. And bandwidth is not really that big of a problem, nor storage space, is it? What I'm suggesting is that it be hard coded, so it’s there, then people can choose. I looked at the size of your documentation

www-sphinx-doc-org-en-master.pdf

It was 3.2Mb that's really not a huge hurdle in size wise

jayaddison,"...Are there particular projects..."

I can't remember the page I wanted, but I got to your software from a link on that page saying they used your software.

picnixz,"...By the way, you can directly download the PDF of the documentation if you click on "v:master"..."

Ok I see this on this page below, it seems to me, not sure, I've seen that once and by pure random error clicked on it, but mostly I don't see, or notice, it.

https://www.sphinx-doc.org/en/master/

And no, I don't get it. Conceptually. If you were to go up to someone, ask them what the "v:master" is, how many do you think would know what you were talking about? In fact, I challenge you to show people the page I linked and ask them what the "v:master" is. If you show people the page above and asked what the "v:master" is, could they give an answer? If however you put it at the bottom, or the top(should be the top as it's the "total" document control), of the left sidebar and called it language selection and whole doc download, and you showed it to someone, would they know what it meant? Of course, they would, and it illustrates the point I’m trying to make. It’s not that your software is not a marvel of modern engineering. It is. It’s fabulous, but some basic common sense stuff, the very basic stuff, is covered in opacity and "unusefulness".

It could be that this mystical "v:master" thing didn't show up on the pages I went to. I use noscript plug-in, Is it in all document pages???? (God help us all, don't get me started on scripts from all over. Do I really need a script from Facebook or TikTok to look at instructions on programming ESP32 microcontrollers), I load what I "guess" is the scripts needed to view the page. No more. Anyone who runs all scripts on their browser, no matter how fast the computer, is in for abuse.

Excuse my sarcasm. But your software seems so useful and full of promise that it annoys me to no end that basic functionality, or as I see it, is covered up in code that doesn't seem logical to me for software that is all about documentation. Should you have to hunt for documentation in documentation software to use it or use another program to use documentation off the grid???

Maybe I’m showing age, more sarcasm, we had these things long ago called...books. And you looked at index and then turned the pages to see what interested us. The part you missed is you can carry books around with you, but can't always carry around the internet.

[picnixz]

I will close this issue since we will not consider the ergonomic aspect of the website which is managed by RTD.

Ok I see this on this page below, it seems to me, not sure, I've seen that once and by pure random error clicked on it, but mostly I don't see, or notice, it.

Well, the button is not managed by us since its the RTD theme that's doing it for us. We could have add link where you click on it to download the PDF but I don't think it's good to duplicate what RTD already provides for a limited number of people. Also, having a download link for each page is a nogo because there are cross-references that you still need.

If you show people the page above and asked what the "v:master" is, could they give an answer

People don't need to know what it means; they just need to know that it's a menu they can open with more things. Again, if you want to complain about the ergonomy of the theme, you should address those complaints to RTD directly.

I load what I "guess" is the scripts needed to view the page. No more. Anyone who runs all scripts on their browser, no matter how fast the computer, is in for abuse.

Then it's your issue if you don't see everything.

we had these things long ago called...books

Sure, you can now print our PDF.

Should you have to hunt for documentation in documentation software to use it or use another program to use documentation off the grid???

Well, before doing this, people ask questions on Stackoverflow in general. But yes. And it's the same for everything. You usually read the manual before using a new tool.

[jayaddison]

I agree, and I'd also like to explain the relationship between Sphinx (this project) and ReadTheDocs (the host of many project documentation sites):

• Sphinx is open source software to build documentation into HTML, PDF, ePub and other formats.
• ReadTheDocs is a documentation hosting company that presents HTML and in some cases PDF/ePub/other single-document downloads for various software projects.

I think that Sam understands these, so my apologies if that is repetitive. However it should also explain the relationships in the "Built with Sphinx using a theme provided by Read the Docs" text in the footer of many project documentation sites.

I'd also agree that it's not entirely clear to someone unfamiliar what the v:master / dropdown menu might contain. That menu is part of the ReadTheDocs theme (custom formatting for Sphinx to use when it builds an HTML site) as explained -- I think they call it the flyout.

What none of us seem to have a record of is the site where a PDF link (an offline format) was unavailable. It's not enabled for projects by default - it has to be configured: https://docs.readthedocs.io/en/stable/guides/enable-offline-formats.html

If we can find the relevant project(s), it'll be possible to contact them, and depending on how the question is asked, they may be glad to enable PDF/other offline formats -- if they agree that they want to. The key is to figure out where to route that request.

[SamtheTruck]

I brought this to your attention because, well I don't like to complain, but I do like the work on this and it would be so nice, if, it were a formatted document that I would not have to be tied to the net. But the outcome is, exactly, what I expected.

"...it'll be possible to contact them, and depending on how the question is asked, they may be glad to enable PDF/other offline formats..."

Hardly anyone is going to do this. I’m not. It’s faster to do it yourself, but that defeats the whole purpose of having computers do drudge work for us in the first place. So what I will do is as I have been and use the plug-in downloadthemall and add a numerical digit to the front of all the files and end up defeating the whole purpose of the whole wonderful document system. A bunch of html files, one for each link, in a folder. It’s sad that in so many ways things keep going backwards. In many cases complexity does not make things better but worse. Features do not equal functionality.

[jayaddison]

So what I will do is as I have been and use the plug-in downloadthemall and add a numerical digit to the front of all the files

Yep, that doesn't seem ideal. Next time you do this: I'd recommend either commenting here and asking me, or finding the GitHub repository for the project whose documentation you're downloading, and creating an issue there to ask that specific project to enable PDF downloads.

The chances are they won't be able to enable it immediately - some projects receive a lot of bugreports, or have maintainers who have multiple responsibilities and aren't able to check the latest items every day - but many bugreports do get fixed, so at some point someone (maybe you) will benefit from your report.

Hardly anyone is going to do this.

True. From personal experience, I didn't report or fix many bugs in the past, but now that I have the time I enjoy doing both. It's one of the reasons that open source software continues to gradually improve over time - however it does require making the effort to do the reporting/fixing. Sometimes it feels like a lot of effort up-front for a small detail, but it does feel good days/weeks/months later when a problem is fixed.