sphinx-doc / sphinx-doc/sphinx
Add hash option to literalinclude (when `:lines:` or `:emphasize-lines:` is set)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Is your feature request related to a problem? Please describe.
When a literally included file is changed it can cause the rendered inclusion to be out of sync with the intended lines to be displayed or emphasized.
Describe the solution you'd like
For there to be a :hash: option that can be set which represents a hash value of the displayed lines.
This could be eg a sha256checksum of the displayed lines, or perhaps just the first 10 chars of a hash.
When sphinx renders the literally included file with this option set it should check the hash of the lines that will be displayed - if they do not match it should throw a warning - something like:
WARNING: hash of literalinclude `filename.txt` with lines 23-73 has changed. Expected hash is `1d4efe44f0` but sphinx found `831fb7081d`
Some additional configuration options may be also be useful, eg:
- hash mechanism
- warning or error
- enforce hashing for literalincludes with lines/emphasize-lines set
it may also be useful to have some kind of utility for generating a hash for a given file or snippet
Describe alternatives you've considered
- manual checking of all literalincludes any time a file that might be literally included changes (very error prone, relies on reviewers knowing of this problem, time consuming)
- storing a config of all literally included files and there current hashes in a repo (relies on contributors understanding the need to update this when literally included files are added or changed, and additional ci to check it)
Additional context
if there is some interest in this feature i may be able to implement (and may create a custom plugin to do this in the meantime)
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
The issue names Sphinx's literalinclude feature but no files or tests. Start by locating the literalinclude implementation and its existing tests, then clarify the hash algorithm, scope of hashing, and warning or error behavior. Done means documented hash support with coverage for matching and changed displayed lines.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100