sphinx-doc / sphinx-doc/sphinx

Make html_sourcelink_suffix default to an empty string

Open
#11,201 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

builder:html internals:config
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:

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.