sphinx-doc / sphinx-doc/sphinx
Make html_sourcelink_suffix default to an empty string
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
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:
- https://github.com/sphinx-doc/sphinx/pull/4022 (relevant lines https://github.com/sphinx-doc/sphinx/pull/4022/files#diff-52f537c2146ef4388e77c5e7616aecdabb7fc09454d03694ae238551b9fc1286L263-R271 )
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: "".
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Locate the definition and default handling for html_sourcelink_suffix, then read the related source-link tests if present. Verify that the default produces links without an added .txt while an explicitly configured suffix still works, and run the relevant tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100