During docs builds, leave newsfragments unchanged

[TeamSpen210]

Fixes #3084: This makes building docs include the changelog, while keeping all source files unchanged. This does that by restoring the working tree copy and any staged changes afterwards. Ideally there'd be an option to have towncrier not git add the changed copy, or write to another location, then we wouldn't have to restore. But this works fine.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.60%. Comparing base (fee3ec0) to head (1beebbf).
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3086      +/-   ##
==========================================
+ Coverage   99.59%   99.60%   +0.01%     
==========================================
  Files         121      121              
  Lines       17882    17882              
  Branches     3214     3214              
==========================================
+ Hits        17809    17811       +2     
+ Misses         51       50       -1     
+ Partials       22       21       -1     

see 1 file with indirect coverage changes

[jakkdl]

Looks good!

Though I just realized a different way of achieving this that's perhaps even better/simpler - move the newsfragments/ directory into docs/source (or include newsfragments/ as an additional source dir... somehow). I don't think we actually gain anything by injecting the content into changelog.rst.
That leaves warnings for document isn't included in any toctree, but if there's no easy way of filtering those out we could either [conditionally] include them in the toctree (which won't make any difference to final docs) or let the developer simply ignore those warnings

[TeamSpen210]

That would check syntax, but this way lets you fully preview how the changelog would appear in context. Sphinx has heaps of events, there definitely would be a way to include newsfragments/ directly + add to the toctree.

[jakkdl]

Day-to-day I usually only care about syntax, previewing in context would be if you care about the specific way towncrier incorporates the fragments. But I suppose others might find that useful at times

[jakkdl]

we can also open an issue/PR in towncrier for a command-line argument that disables staging the changelog

[jakkdl]

I want this now for working on #3081, so I'll merge it :)

[jakkdl]

Works great! One downside is that the sphinx output will refer to non-existent lines, but shouldn't be very difficult to trace back to where they came from - though could cause confusion in the future if people aren't aware that this is happening behind the curtains.

.../docs/source/history.rst:14: WARNING: undefined label: 'saved_relative_timeouts'
.../docs/source/history.rst:28: WARNING: undefined label: 'saved_relative_timeouts'

[TeamSpen210]

Hmm. Actually, looking for how to solve that gave me an idea for a totally different way to do this that would simplify the git bit, and solve a few problems. We have towncrier "modify" a blank file to get the changelog it produces, then use an RST include directive to insert that into the history file dynamically. Then the line numbers will be correct, we don't have to revert the real history, and as a bonus you'd be able to inspect the new file to see the new source.

[jakkdl]

Hmm. Actually, looking for how to solve that gave me an idea for a totally different way to do this that would simplify the git bit, and solve a few problems. We have towncrier "modify" a blank file to get the changelog it produces, then use an RST include directive to insert that into the history file dynamically. Then the line numbers will be correct, we don't have to revert the real history, and as a bonus you'd be able to inspect the new file to see the new source.

The downside to that would be that you now have a dangling dead file you 1. "need" to clean up, and 2. you can confuse yourself by editing the generated file instead of the original fragments, and 3. getting an error in there requires you to open the file, identify the line that caused the error, figure out which newsfragment file that corresponds to, and then go edit it.
These are fairly marginal, and probably better than the status quo, but I think for my personal day-to-day of wrangling with references and formatting in newsfragments it'd be better to directly check the fragments. Needing to debug how towncrier combines fragments is far less useful to me personally

[TeamSpen210]

I was thinking the dangling file would be gitignored, so you could just leave it, and it'd have a comment at the start to tell you not to edit. The filename being not as useful could maybe be solved by even more indirection, have the temp history file include the original newsfragements. That'd definitely need to be implemented in towncrier, and it also is a little over complicated...