From 8d7a8f0f98b46b4c351374aa3d8003fd71585cc7 Mon Sep 17 00:00:00 2001
From: "James R. Barlow" <james@purplerock.ca>
Date: Sat, 31 Aug 2024 01:14:51 -0700
Subject: [PATCH] Update documentation to transition from setuptools to
 hatchling

---
 docs/installation.rst  |  5 ++---
 docs/maintainers.rst   |  5 +++--
 docs/plugins.rst       | 21 +++++++++------------
 docs/release_notes.rst | 10 ++++++++++
 4 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/docs/installation.rst b/docs/installation.rst
index cc0573b4b..90fcaec0e 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -341,7 +341,7 @@ OCRmyPDF is includes in MacPorts:
     sudo port install ocrmypdf
 
 Note that while this will install tesseract you will need to install
-the appropriate tesseract `language ports <https://ports.macports.org/search/?selected_facets=categories_exact%3Atextproc&installed_file=&q=tesseract&name=on>`__. 
+the appropriate tesseract `language ports <https://ports.macports.org/search/?selected_facets=categories_exact%3Atextproc&installed_file=&q=tesseract&name=on>`__.
 
 Manual installation on macOS
 ----------------------------
@@ -640,8 +640,7 @@ environment:
 
     pip install git+https://github.com/ocrmypdf/OCRmyPDF.git
 
-Or, to install in `development
-mode <https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#working-in-development-mode>`__,
+Or, to install in editable mode
 allowing customization of OCRmyPDF, use the ``-e`` flag:
 
 .. code-block:: bash
diff --git a/docs/maintainers.rst b/docs/maintainers.rst
index 0a84229aa..33c77cb89 100644
--- a/docs/maintainers.rst
+++ b/docs/maintainers.rst
@@ -38,12 +38,13 @@ on ARM and x86_64. Performance may be poor on other processor architectures.
 Versioning scheme
 -----------------
 
-OCRmyPDF uses setuptools-scm for versioning, which derives the version from
+OCRmyPDF uses hatch-vcs for versioning, which derives the version from
 Git as a single source of truth. This may be unsuitable for some distributions, e.g.
 to indicate that your distribution modifies OCRmyPDF in some way.
 
 You can patch the ``__version__`` variable in ``src/ocrmypdf/_version.py`` if
-necessary.
+necessary, or set the environment variable ``SETUPTOOLS_SCM_PRETEND_VERSION``
+to the required version, if you need to override versioning for some reason.
 
 jbig2enc
 --------
diff --git a/docs/plugins.rst b/docs/plugins.rst
index 558e743f5..3f8564cda 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -29,6 +29,9 @@ conventions. Note that: plugins installed with as setuptools entrypoints are
 not checked currently, because OCRmyPDF assumes you may not want to enable
 plugins for all files.
 
+See [OCRmyPDF-EasyOCR](https://github.com/ocrmypdf/OCRmyPDF-EasyOCR) for an
+example of a straightforward, fully working plugin.
+
 Script plugins
 ==============
 
@@ -70,14 +73,15 @@ similar to ``pytest`` packages such as ``pytest-cov`` (the package) and
     module), just like pytest plugins. At the same time, please make it clear
     that your package is not official.
 
-Setuptools plugins
-==================
+Plugins
+=======
 
 You can also create a plugin that OCRmyPDF will always automatically load if both are
-installed in the same virtual environment, using a setuptools entrypoint.
+installed in the same virtual environment, using a project entrypoint.
+OCRmyPDF uses the entrypoint namespace "ocrmypdf".
 
-Your package's ``pyproject.toml`` would need to contain the following, for a plugin
-named ``ocrmypdf-exampleplugin``:
+For example, ``pyproject.toml`` would need to contain the following, for a plugin named
+``ocrmypdf-exampleplugin``:
 
 .. code-block:: toml
 
@@ -87,13 +91,6 @@ named ``ocrmypdf-exampleplugin``:
     [project.entry-points."ocrmypdf"]
     exampleplugin = "exampleplugin.pluginmodule"
 
-.. code-block:: ini
-
-    # equivalent setup.cfg
-    [options.entry_points]
-    ocrmypdf =
-        exampleplugin = exampleplugin.pluginmodule
-
 Plugin requirements
 ===================
 
diff --git a/docs/release_notes.rst b/docs/release_notes.rst
index 33a8564a6..0803be371 100644
--- a/docs/release_notes.rst
+++ b/docs/release_notes.rst
@@ -30,6 +30,16 @@ OCRmyPDF typically supports the three most recent Python versions.
 
 .. |OCRmyPDF PyPI| image:: https://img.shields.io/pypi/v/ocrmypdf.svg
 
+v16.5.0
+=======
+
+-  Presumably fixed issue with interpreting PDFs that have images with array masks.
+   :issue:`1377`
+-  Enabled testing on Python 3.13.
+-  Fixed a test that did not work correctly but still passed. :issue:`1382`
+-  Improved "PDF/A conversion failed" warning message to better describe implications.
+-  Updated documentation to better explain OCR_JSON_SETTINGS in batch processing.
+
 v16.4.3
 =======