feature: Update functionality

[SecondSkoll]

Adds a script that:

• Checks the version of the starter pack (a local file) against the latest release tag.
• Does some comparisons with the starter pack remote repo, and checks the SHA of specific files (files in .sphinx) to identify files that are out of date and download them to .sphinx/update where they can be easily diff'd and manually merged in.
• Identifies new files as well as files with differences.
• Checks the local requirements against the requirements listed in the latest release of the starter pack.
• Prints the latest section of changelog (from latest to the local version, e.g. if my local is on 1.2.0 and latest is 1.2.1 it just prints 1.2.1's changelog section).

Reorganises some files so files likely to be changed are not affected. All files in the .sphinx directory should now be considered static, though there are still some edge cases like the MD linting file (different people like and dislike line length checks). This includes project_specific.css and the _static folder, and requirements.txt.

Removes MD013 by default (decision can be made later but line length is not checked in other markup, and this is more consistent).

Adds a changelog file for listing changes to the starter pack, for easier knowledge of updates and changes. This will be separate to release notes, as it identified files that have been changed - rather than the purpose of the changes themselves.

Adds update Make target.

Changes and disables local static and templates path. This can be re-enabled by uncommenting them.

[SecondSkoll]

TO DO:

• Change URLs from my fork to the main repository.
• Document the feature.
• Test against some relatively up to date documentation sets.

Additional considerations:

• There is no checking of the Make file and its contents.
• There is no checking of the conf.py file and its contents.
• There is no checking of the .readthedocs.yaml file and its contents.
• There is no checking of the GitHub workflows.

Are these high value targets for additional checks? Similar SHA checks will work for RTD and GitHub files, but it's more complex to check Make and conf.py.

[SecondSkoll]

Something I feel I should clarify: This is deliberately not as automated as it could be.

We want things to be relatively simple, and work out of the box, but we also want users to be aware of the moving pieces within the starter pack and how it functions. That's why this is focused on making it easier to update, and making changes more visible.

Users should be using this script to understand the changes that are being made, and to be able to enact those changes themselves. Instead of digging through git to understand changes and see what files have been changed, these changes are presented directly to users and files are provided for users to diff or choose to drop in themselves.

I believe this aligns well with our efforts in documentation - making deliberate, conscious choices, while also making the starter pack easier for users.

[SecondSkoll]

Refactored and implemented retaining exit codes as inspired by @tang-mm's work in #358. Adjusted exceptions to not completely fail out on some common issues (should roughly support older versions of the starter pack with warnings about it probably being funny). Added logging, so you can get more info by running the script with DEBUGGING=1 python3 .sphinx/update_sp.py. Ran Ruff for general linting and formatting.

[SecondSkoll]

I think it's best to stick with this level for now, and iterate and expand to the other files later if there's a strong need. The other files are either very static or would require different approaches to validating content. The Makefile and conf.py file will be difficult to validate as they can be significantly customised, the main workflow should be static given it's a remote action we can alter there instead, and the RTD also needs customisation for some projects.

We can think through some other implementation for validating conf.py and the Makefile if we consider it problematic, but I'm hoping the approach with the changelog file is able to fill that need.

[tang-mm]

Kudos for compiling the changes! I see the logic involved is complex.
I have left comments in various sections, including several minor nitpicks about references. I also labeled issues that need to be addressed, but open for discussion!

[dwilding]

You mentioned that this PR doesn't include documentation about the update functionality (which personally I think is fine, because the update functionality will only become relevant at the version after the version that introduces the update functionality). But I do see some parts of the existing docs that mention .sphinx/requirements.txt, .sphinx/_static, and .sphinx/_templates. Would you like me to help update?

Also, I'm wondering whether we should consider .sphinx/spellingcheck.yaml to be static. We had to modify it in a project to bulk ignore portions of generated docs. I guess that's rare enough that it's not worth trying to move the file out of .sphinx. But is it going to cause issues with the update functionality if that file has been customised?

[SecondSkoll]

You mentioned that this PR doesn't include documentation about the update functionality (which personally I think is fine, because the update functionality will only become relevant at the version after the version that introduces the update functionality). But I do see some parts of the existing docs that mention .sphinx/requirements.txt, .sphinx/_static, and .sphinx/_templates. Would you like me to help update?

Also, I'm wondering whether we should consider .sphinx/spellingcheck.yaml to be static. We had to modify it in a project to bulk ignore portions of generated docs. I guess that's rare enough that it's not worth trying to move the file out of .sphinx. But is it going to cause issues with the update functionality if that file has been customised?

We'll need to update documentation before it's merged but I'm more focused on the functionality at this point. If we need to rethink how things are done we don't want to spend time documenting something we then might have to revert.

I think spellingcheck.yaml is fine to be considered static because it will be replaced later this cycle by Vale's spelling check, and the update script won't automatically overwrite any files, it will just indicate some files are different and download those files so you can compare them or drop them in yourself.

[tang-mm]

Thanks for considering all the feedback!