Use shortened links for issues in docs (#56)

We can now link to issues in the docs by writing :issue:`#<issue_number>`, which is very nice and convenient for release notes.

Courtesy of Simon Willison finding and writing this up at: https://til.simonwillison.net/sphinx/sphinx-ext-extlinks

Author: Mr0grog

docs/source/conf.py

@@ -40,6 +40,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
+    'sphinx.ext.extlinks',
     'sphinx.ext.githubpages',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
@@ -63,6 +64,11 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Set up link shortcuts
+extlinks = {
+    'issue': ('https://github.com/edgi-govdata-archiving/web-monitoring-diff/issues/%s', '#'),
+}
+
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),

docs/source/release-history.rst

@@ -5,23 +5,23 @@ Release History
 Version 0.1.2rc1 (2021-01-01)
 -----------------------------
 
-- The server uses a pool of child processes to run diffs. If the pool breaks while running a diff, it will be re-created once, and, if it fails again, the server will now crash with an exit code of ``10``. (An external process manager like Supervisor, Kubernetes, etc. can then decide how to handle the situation.) Previously, the diff would fail at this point, but server would try to re-create the process pool again the next time a diff was requested. You can opt-in to the old behavior by setting the ``RESTART_BROKEN_DIFFER`` environment variable to ``true``. (`#49 <https://github.com/edgi-govdata-archiving/web-monitoring-diff/issues/49>`_)
+- The server uses a pool of child processes to run diffs. If the pool breaks while running a diff, it will be re-created once, and, if it fails again, the server will now crash with an exit code of ``10``. (An external process manager like Supervisor, Kubernetes, etc. can then decide how to handle the situation.) Previously, the diff would fail at this point, but server would try to re-create the process pool again the next time a diff was requested. You can opt-in to the old behavior by setting the ``RESTART_BROKEN_DIFFER`` environment variable to ``true``. (:issue:`49`)
 
 
 Version 0.1.1 (2020-11-24)
 --------------------------
 
 This is a bugfix release that focuses on :func:`web_monitoring_diff.html_diff_render` and the server.
 
-- Fix an issue where the diffing server could reset the process pool that manages the actual diffs multiple times unnecessarily, leading to wasted memory and CPU. If you are tracking logs and errors, this will also make error messages about the diffing server clearer — you’ll see “BrokenProcessPool” instead of “'NoneType' object does not support item assignment.” (`#38 <https://github.com/edgi-govdata-archiving/web-monitoring-diff/issues/38>`_)
+- Fix an issue where the diffing server could reset the process pool that manages the actual diffs multiple times unnecessarily, leading to wasted memory and CPU. If you are tracking logs and errors, this will also make error messages about the diffing server clearer — you’ll see “BrokenProcessPool” instead of “'NoneType' object does not support item assignment.” (:issue:`38`)
 
-- Ensure the server shuts down gracefully when pressing ctrl+c or sending a SIGINT signal. (`#44 <https://github.com/edgi-govdata-archiving/web-monitoring-diff/issues/44>`_)
+- Ensure the server shuts down gracefully when pressing ctrl+c or sending a SIGINT signal. (:issue:`44`)
 
-- Fix :func:`web_monitoring_diff.html_diff_render` to make sure the spacing of text and tags in the HTML source code of the diff matches the original. This resolves display issues on pages where CSS is used to treat spacing as significant. (`#40 <https://github.com/edgi-govdata-archiving/web-monitoring-diff/issues/40>`_)
+- Fix :func:`web_monitoring_diff.html_diff_render` to make sure the spacing of text and tags in the HTML source code of the diff matches the original. This resolves display issues on pages where CSS is used to treat spacing as significant. (:issue:`40`)
 
-- Improve handling of lazy-loaded images in :func:`web_monitoring_diff.html_diff_render`. When images are lazy-loaded via JS, they usually use the ``data-src`` or ``data-srcset`` attributes, and we now check those, too. Additionally, if two images have no detectable URLs, we now treat them as the same, rather than different. (`#39 <https://github.com/edgi-govdata-archiving/web-monitoring-diff/issues/39>`_)
+- Improve handling of lazy-loaded images in :func:`web_monitoring_diff.html_diff_render`. When images are lazy-loaded via JS, they usually use the ``data-src`` or ``data-srcset`` attributes, and we now check those, too. Additionally, if two images have no detectable URLs, we now treat them as the same, rather than different. (:issue:`39`)
 
-- Stop showing inline scripts and styles in :func:`web_monitoring_diff.html_diff_render`. These still get wrapped with ``<del>`` or ``<ins>`` elements, but they don’t show up visually since they aren’t elements that should be visually rendered. (`#43 <https://github.com/edgi-govdata-archiving/web-monitoring-diff/issues/43>`_)
+- Stop showing inline scripts and styles in :func:`web_monitoring_diff.html_diff_render`. These still get wrapped with ``<del>`` or ``<ins>`` elements, but they don’t show up visually since they aren’t elements that should be visually rendered. (:issue:`43`)
 
 
 Version 0.1.0