Fix: convert remote image directives in README.rst to hyperlinks to unblock PyPI publish

[Copilot]

twine check dist/* fails during the publish workflow because docutils attempts to fetch remote images embedded in README.rst (the PyPI long description), producing: Requires Python Imaging Library. Reading external files disabled.

Changes

• README.rst: Replace all .. image:: directives pointing to remote URLs with plain RST hyperlinks:
  • CI/Zenodo badge directives → inline hyperlinks (`CI Status <...>`_)
  • Nine example figure directives (figure_1.png … figure_16b.png) → `View figure_N.png <...>`_ links

Before:

.. image:: https://raw.githubusercontent.com/rilma/pyHWM14/main/graphics/figure_1.png
    :scale: 100 %

After:

`View figure_1.png <https://raw.githubusercontent.com/rilma/pyHWM14/main/graphics/figure_1.png>`_

No workflow changes. No code changes. Fix is strictly scoped to the README content that feeds PyPI metadata validation.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• My code follows the project style guidelines (black, ruff, mypy)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added tests that prove my fix/feature works
• New and existing tests pass with my changes
• Test coverage remains > 80%
• I have updated the documentation (docstrings, README, guides)
• I have added an entry to CHANGELOG.md
• I have updated type hints for modified functions

Testing

# Verify no image directives remain
grep -n '^\.\. image::' README.rst  # should return nothing

# Validate RST renders without errors
python -m docutils README.rst /dev/null

# Full publish-gate check (after building dist/)
python -m twine check dist/*

Additional Context

Root cause: PyPI's readme renderer and twine check both invoke docutils without network/PIL access. Any .. image:: directive with a remote URL triggers a file-read attempt that fails. Converting to hyperlinks preserves the visual links on GitHub while making the RST safe for PyPI metadata validation.

Original prompt

Create a pull request in repository rilma/pyHWM14 to fix the failing publish workflow job in GitHub Actions run 25886422864 (job 76079152133).

Context:

• The failing workflow is .github/workflows/release-pypi.yaml.
• The failure happens during python -m twine check dist/*.
• The job log shows this error:
  • "https://raw.githubusercontent.com/rilma/pyHWM14/main/graphics/figure_1.png": Requires Python Imaging Library. Reading external files disabled.
• pyproject.toml uses README.rst as the package long description (readme = "README.rst").
• Therefore the package metadata validation fails because README.rst includes remote image references.

Requested fix:

• Implement the minimal patch by editing README.rst.
• Convert remote image references in README.rst to normal hyperlinks instead of image directives.
• Do not change the workflow unless absolutely necessary.
• Keep the fix focused on making twine check pass for package publishing.

Acceptance criteria:

1. README.rst no longer contains remote image directives that trigger docutils/twine external file reading during metadata validation.
2. Any remote image references are converted to ordinary hyperlinks or equivalent non-image text links.
3. The change is minimal and targeted.
4. Open a pull request with the fix.

Please inspect the repository as needed to update the correct file(s) and create the PR.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Please find a solution for this failing job. Use the logs, job definition, and any referenced files where the failure occurred. Keep your response focused on the solution and include code suggestions when appropriate.

Assistant: The failure is caused by twine check trying to render your long description from README.rst, which includes a remote image URL:

• Failing workflow step: .github/workflows/release-pypi.yaml
• Error from the job log: Requires Python Imaging Library. Reading external files disabled.
• Package metadata points to README.rst as the PyPI long description: pyproject.toml

Solution

Update README.rst so PyPI metadata validation does not reference remote images. The safest fix is to remove or replace the external image in the README used for packaging.

Recommended change

If you have something like this in README.rst:

.. image:: https://raw.githubusercontent.com/rilma/pyHWM14/main/graphics/figure_1.png

replace it with one of these options:

Option 1: Remove the image from the package README

.. note::

   See the GitHub repository for figures and rendered examples:
   https://github.com/rilma/pyHWM14

Option 2: Use a GitHub-relative link only in docs, not in the PyPI README

For the README used by PyPI, avoid image directives entirely.

Why this works

twine check dist/* validates the rendered description before publish. PyPI/readme rendering does not allow fetching external files during validation, so the remote PNG in README.rst breaks the build.

Optional workflow hardening

If you want to catch this earlier and more explicitly, keep this validation step as-is:

- name: Validate built artifacts
  run: python -m twine check dist/*

That step is already correct in .github/workflows/release-pypi.yaml#L111-L112. The fix belongs in the README content, not the workflow.

Minimal patch idea

In README.rst, remove the remote raw.githubusercontent.com/.../figure_1.png image reference or convert it to plain text/a normal hyperlink. After that, rebuild the sdist/wheel and twine check should pass.

User: Can you implement the Minimal patch idea through a Pull Request? If so, then convert the remote image references to a normal hyperlink, as suggested above.

Assistant: Yes — I’ve started the pull request creation for rilma/pyHWM14 with the requested minimal fix: converting the remote image references in README.rst into normal hyperlinks so the publish workflow can pass twine check.

This pull request was created from Copilot chat.