Fix duplicate reStructuredText substitution definitions in docstrings

[Copilot]

Description

Sphinx documentation build was failing with 12 "Duplicate substitution definition name" errors. reStructuredText substitution definitions (e.g., .. _name: and .. |name|) are global scope—defining them in both sync and async method docstrings caused conflicts.

Changes:

• Removed duplicate substitution definitions from 10 async methods
• Kept definitions in sync methods only
• Preserved all substitution references (|name|_) in both sync and async docstrings

Affected methods:

• create_queue_async, create_partitioned_queue_async, drop_queue_async
• read_async, read_with_poll_async, set_vt_async
• delete_async, delete_batch_async, archive_async
• metrics_all_async

Documentation now builds successfully with no errors or warnings.

Status

• In progress
• Ready for review
• Done

Checklist

• Read the Contributing Guide
• Passes tests
• Linted ( we use pre-commit with ruff )
• Updated documentation

Original prompt

Fix build doc error:

---

/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.create_queue_async:2: ERROR: Duplicate substitution definition name: "unlogged_table". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.create_partitioned_queue_async:4: ERROR: Duplicate substitution definition name: "pgmq_partitioned_queue". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.drop_queue_async:4: ERROR: Duplicate substitution definition name: "drop_queue_method". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.read_async:2: ERROR: Duplicate substitution definition name: "for_update_skip_locked". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.read_async:5: ERROR: Duplicate substitution definition name: "read_method". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.read_with_poll_async:2: ERROR: Duplicate substitution definition name: "read_with_poll_method". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.set_vt_async:2: ERROR: Duplicate substitution definition name: "set_vt_method". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.delete_async:4: ERROR: Duplicate substitution definition name: "delete_method". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.delete_batch_async:4: ERROR: Duplicate substitution definition name: "delete_batch_method". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.archive_async:4: ERROR: Duplicate substitution definition name: "archive_method". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.metrics_all_async:2: ERROR: Duplicate substitution definition name: "read_committed_isolation_level". [docutils]
/home/docs/checkouts/readthedocs.org/user_builds/pgmq-sqlalchemy/checkouts/latest/pgmq_sqlalchemy/queue.py:docstring of pgmq_sqlalchemy.queue.PGMQueue.metrics_all_async:5: ERROR: Duplicate substitution definition name: "metrics_all_method". [docutils]

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines	Coverage Δ
pgmq_sqlalchemy/queue.py	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.