search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

Make html_sourcelink_suffix default to an empty string #11201

Open choldgraf opened 1 year ago

choldgraf commented 1 year ago

Currently, html_sourcelink_suffix defaults to .txt. This means that all of the sourcelinks have .txt appended to them. So for example, myfile.rst becomes myfile.rst.txt. I believe that this was done in order to improve search results that were erroneously returning rST source content:

For this reason, the source files were converted to text files and those files were then used for the search.

However, I believe that in the following PR, this behavior was changed to instead parse the HTML files themselves, rather than the file sources:

Meanwhile, it confuses users when they try to download the source file of a page, but that file ends in .txt. In my experience, it confuses users when they expect to download an .rst or .md file, and instead they get an .rst.txt or .md.txt file (or worse, a .ipynb.txt). Programs that adjust their behavior due to the file extension do not behave properly, and it adds an extra step users must follow to manually delete the .txt.

I can't think of a reason why a reader would want to have .txt appended to the source file when they download it. So my proposal is that the default value of html_sourcelink_suffix be set to an empty string: "".

mgeier commented 1 year ago

Currently, html_sourcelink_suffix defaults to .txt. [...] I believe that this was done in order to improve search results that were erroneously returning rST source content

I think you got the chronology and causation a bit wrong.

In the beginning, the html_sourcelink_suffix option didn't exist, and .txt was used unconditionally as an extension for all source links.

Then, I added the html_sourcelink_suffix option in #2454, where I used .txt as a default value for backwards compatibility.

The issue #1618 kind of happened in parallel, but it was not the reason for selecting .txt as extension. I guess the .txt extension was there since the source link feature existed.

As for the reason why .txt was originally chosen, see this ancient mailing list thread: https://groups.google.com/g/sphinx-dev/c/q8dGyV6dN4A

I have the feeling that those arguments are still mostly valid, and I have accepted the default value and added the suggestion to use an empty string to the nbsphinx documentation: https://nbsphinx.readthedocs.io/en/0.8.12/configuration.html#html_sourcelink_suffix.

I don't know how many people are using this setting, though.

Nowadays, I don't use html_copy_source at all, because the download link behaves clumsily anyway (as discussed in the mailing list thread). Instead, I use an auto-generated link to the Github (or GitLab or Bitbucket) page of the (appropriate version of) the source file.

The insipid theme supports this on RTD out of the box, see https://insipid-sphinx-theme.readthedocs.io/en/0.4.1/configuration.html#confval-html_show_sourcelink.

It would be great if other themes could also support this, which might make the discussion about html_sourcelink_suffix obsolete in the long run (but it might start a discussion about html_copy_source instead).

choldgraf commented 1 year ago

Ah that's an aspect of the .txt extension I hadn't considered. Thanks for linking to the context.

For what it's worth I still think the net effect on users is "confusion" given that they expect something to be one extension, and instead they get something with .txt . My preference would be for sphinx to default to not being clever and ask the site author to decide to change the behavior. That said, if it's already been discussed and decided against, then I'm fine just closing this issue.

Agreed that it is much more convenient to be able to point to the GitHub source rather than the raw text file (if the file is hosted in one of those places). Maybe I'll explore how to do that in the book theme!

RokeJulianLockhart commented 6 months ago

https://bugzilla.mozilla.org/show_bug.cgi?id=1892031#c0