How are writers chosen (and how to chose a specific one for man output)?

[krobelus]

Sphinx provides a manpage writer,
and so does docutils.

• when I run the script below, I see that
  • in a minimal python environment (provided by uv), the Sphinx manpage writer is used
  • when I run with /bin/sphinx-build, the docutils writer is used
• I'd like to find out how this selection is done,
  (also, why does this naming conflict exist?)
• I want to predictably use a writer that outputs OSC 8 links, I don't think the docutils one does.

set -e
mkdir t/repro
mkdir t/repro/src
echo > t/repro/src/conf.py ''
echo > t/repro/src/index.rst '
`this is a test link <https://pubs.opengroup.org/onlinepubs/9699919799/utilities/test.html>`__
'
set -- sphinx-build -q -b man -c t/repro/src -d t/repro/out t/repro/src
uv run --no-env-file --no-managed-python --with sphinx==8.2.3 "$@" t/repro/out-uv
"$@" t/repro/out-pacman
set -x
grep -R "X'tty" t/repro/out-uv # present
grep -R "X'tty" t/repro/out-pacman ||: # missing
diff -u t/repro/out-uv/projectnamenotset.1 t/repro/out-pacman/projectnamenotset.1

+ grep -R X'tty t/repro/out-uv
t/repro/out-uv/projectnamenotset.1:\X'tty: link https://pubs.opengroup.org/onlinepubs/9699919799/utilities/test.html'\fI\%this is a test link\fP\X'tty: link'
+ grep -R X'tty t/repro/out-pacman
+ :
+ diff -u t/repro/out-uv/projectnamenotset.1 t/repro/out-pacman/projectnamenotset.1
--- t/repro/out-uv/projectnamenotset.1	2025-11-07 23:10:14.348696172 +0100
+++ t/repro/out-pacman/projectnamenotset.1	2025-11-07 23:10:15.311439919 +0100
@@ -1,4 +1,5 @@
-.\" Man page generated from reStructuredText.
+.\" Man page generated from reStructuredText
+.\" by the Docutils 0.22.3 manpage writer.
 .
 .
 .nr rst2man-indent-level 0
@@ -30,8 +31,7 @@
 .TH "PROJECTNAMENOTSET" "1" "Nov 07, 2025" "" "Project name not set"
 .SH NAME
 projectnamenotset \- Project name not set 
-\X'tty: link https://pubs.opengroup.org/onlinepubs/9699919799/utilities/test.html'\fI\%this is a test link\fP\X'tty: link'
-.SH AUTHOR
+this is a test link \%<https://\:pubs\:.opengroup\:.org/\:onlinepubs/\:9699919799/\:utilities/\:test\:.html>
+.SH Author
 Author name not set
-.\" Generated by docutils manpage writer.
-.
+.\" End of generated man page.

[krobelus]

I wonder why the writers diverge. There was some earlier conversation here.
I don't know much about sphinx/docutils but I think it would be nice to have a single manpage writer that works for everyone, or at least have one of the two be a superset of the other.

Specifically, I'd like to add OSC 8 links. Reading https://docutils.sourceforge.io/docs/user/manpage.html, it seems they have a macro-references options (not sure how to set that?), which might work.

[krobelus]

Ah it's because uv uses docutils 0.21.2, while my OS packages docutils 0.22,
which is explicitly not supported by sphinx 8.2.3.

$ pacman -Q python-sphinx python-docutils
python-sphinx 8.2.3-1
python-docutils 1:0.22.3-1

$ git grep '"docutils' v8.2.3 pyproject.toml
v8.2.3:pyproject.toml:    "docutils>=0.20,<0.22",

The next sphinx release should fix that:

$ git grep '"docutils' origin/master pyproject.toml
origin/master:pyproject.toml:    "docutils>=0.20,<0.23",