Fix sphinx incremental builds; add make serve to run sphinx-autobuild

[cspotcode]

Doc server w/automatic rebuild and livereload

make serve will:

• build the docs
• host a webserver for the docs
• watch filesystem for file changes
• when files change, docs will immediately rebuild and your browser will automatically reload the page

This is done with sphinx-autobuild

Fixed incremental builds

Normal sphinx-build has also benefited, because this PR fixes incremental builds. There were two problems:

sitemap broke pickling

Sphinx accomplishes incremental builds by pickling its state, then reloading that pickled object when it starts the next build. The sitemap plugin recently made a change that broke pickling. This meant sphinx was forced to start from scratch every time.

This PR moves back to an older version of the sitemap plugin, until the fix is published to pypi: jdillard/sphinx-sitemap#62

util/ scripts always invalidated cache

When rewriting a file, even if you write the exact same contents to disk, you invalidate sphinx cache. I suspect this is caused by changing a file's modification timestamp.

This PR tweaks the util/ scripts to use a virtual filesystem abstraction that avoids any unnecessary fs writes, if the regenerated file in memory matches what is already on disk.

[pvcraven]

• Might want to add a comment ahead of the library so someone (like me) doesn't re-up that library version.
• Might need to add docs for 'make serve' somewhere?
• Does this work for Mac/Linux both? Maybe WSL?

[cspotcode]

I added a comment about the sitemap version and updated CONTRIBUTING.md to describe how to run make serve. Second opinion welcome on the docs, I wasn't sure whether to fully replace what was there, so I put make serve first and left the old one as a fallback.

Does this work for Mac/Linux both? Maybe WSL?

I actually tested this on Windows, not WSL. I have make installed via scoop install make https://scoop.sh/#/apps?q=make&s=0&d=1&o=true

I can test in WSL2, but I don't have access to a Mac.

[cspotcode]

I also fixed an unrelated bug where create_resource_listing.py was trying to import the globally installed arcade instead of the local one. I suspect that devs usually do not notice this because they have already done pip install -e .[dev], so any import arcade already redirects to the local copy.

However, I work with multiple git worktrees, so it's important for the scripts to always import their own local version of the sources, whatever that is.

[pushfoo]

tl;dr make serve works after re-installing under Linux (Debian 11), but the instructions are currently ambiguous and hard to follow for beginners.

First, thank you for working on this. It will be a massive improvement to the current development & build process. I tested it on Debian Linux.

However, I think we need to make the following changes:

1. Clarify some of the instructions
2. Add instructions on re-installing arcade, and make an announcement for contributors on the Discord server reminding them to re-install the package

[einarf]

Can't we just make this into a pythons script like https://github.com/pyglet/pyglet/blob/master/make.py

[cspotcode]

Can't we just make this into a pythons script like https://github.com/pyglet/pyglet/blob/master/make.py

Should we move that to a Discord thread? I have some opinions about improvements to arcade's build scripts. However, for this PR, I'm trying to embrace what's already there, under the assumption that the team has chosen the current tooling for a good reason.

[pushfoo]

tl;dr works locally after reinstalling; anyone writing doc needs this yesterday

I think benefits of < 10 sec rebuild are worth helping a few people update their doc build setup