sphinx-doc / sphinx-doc/sphinx

Add hash option to literalinclude (when `:lines:` or `:emphasize-lines:` is set)

Open
#9,256 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:enhancement
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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.