manpages broken with latest Sphinx

[neersighted]

Depending on the version of Sphinx you build the docs with, fish will place its manpages in an incorrect section directory -- /usr/share/fish/man/man1/1, instead of /usr/share/fish/man/man1. This is because of a change in Sphinx behavior, causing Sphinx to generate its own set of section directories.

The commits/issues for this are the following:

• Feature Request
• Implementation
• On-by-default

The fix is pretty simple:

diff --git i/doc_src/conf.py w/doc_src/conf.py
index b96203ec1..61f4d3e6f 100644
--- i/doc_src/conf.py
+++ w/doc_src/conf.py
@@ -211,6 +211,8 @@ def get_command_description(path, name):
     raise SphinxWarning("No description in file %s" % os.path.basename(path))
 
 
+man_make_section_directory = False
+
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [

But I think it might be worth backporting to the 3.2.x series and releasing this with the next minor patch since this is a rather annoying bug in released versions.

[faho]

But I think it might be worth backporting to the 3.2.x series and releasing this with the next minor patch since this is a rather annoying bug in released versions.

We do not typically backport fixes because we do not have the manpower to handle multiple release tracks.

---

I can't reproduce this with sphinx 4.0.1. The manpages end up in /usr/share/fish/man/man1 as expected, running man string shows me our string manpage, not the tcl one.

Anyway, if you say this is an issue, must be something on my end fixing it inadvertently.

[faho]

sphinx-doc/sphinx#9232 undoes the default for sphinx 4.0.2. We still want to keep the setting off, because we don't generate man pages outside of section 1 anyway.

I'm still not sure why I can't reproduce on my end - arch did revert the change in archlinux/svntogit-community@6d048e4#diff-3e341d2d9c67be01819b25b25d5e53ea3cdf3a38d28846cda85a195eb9b7203a, but that happened after I tested.