unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* [PATCH] doc: fix man page build for Sphinx 4.x
@ 2021-05-18 21:40 Jani Nikula
  2021-05-18 23:27 ` David Bremner
  2021-05-19 11:57 ` David Bremner
  0 siblings, 2 replies; 5+ messages in thread
From: Jani Nikula @ 2021-05-18 21:40 UTC (permalink / raw)
  To: notmuch; +Cc: jani

Sphinx 4.0 changed the default value of man_make_section_directory
from False to True. We create the section directories and move the
files manually, so fix the immediate man build failure by disabling
the feature.

The Sphinx documentation on this [1] is confusing, and has the change
backwards. Git history says the default changed from False to True.

[1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-man_make_section_directory
---
 doc/conf.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/conf.py b/doc/conf.py
index 1a5c217bb91e..d0f7f66ce83e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -87,6 +87,8 @@ html_use_smartypants = False
 
 notmuch_authors = u'Carl Worth and many others'
 
+man_make_section_directory = False
+
 man_pages = [
     ('man1/notmuch', 'notmuch',
      u'thread-based email index, search, and tagging',
-- 
2.30.2

^ permalink raw reply related	[flat|nested] 5+ messages in thread

* Re: [PATCH] doc: fix man page build for Sphinx 4.x
  2021-05-18 21:40 [PATCH] doc: fix man page build for Sphinx 4.x Jani Nikula
@ 2021-05-18 23:27 ` David Bremner
  2021-05-19  5:45   ` Jani Nikula
  2021-05-19 11:57 ` David Bremner
  1 sibling, 1 reply; 5+ messages in thread
From: David Bremner @ 2021-05-18 23:27 UTC (permalink / raw)
  To: Jani Nikula, notmuch

Jani Nikula <jani@nikula.org> writes:

>
> The Sphinx documentation on this [1] is confusing, and has the change
> backwards. Git history says the default changed from False to True.
>
> [1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-man_make_section_directory

Maybe the docs were corrected?

    Changed in version 4.0: The default is changed to False from True.

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] doc: fix man page build for Sphinx 4.x
  2021-05-18 23:27 ` David Bremner
@ 2021-05-19  5:45   ` Jani Nikula
  2021-05-19 10:45     ` David Bremner
  0 siblings, 1 reply; 5+ messages in thread
From: Jani Nikula @ 2021-05-19  5:45 UTC (permalink / raw)
  To: David Bremner, notmuch

On Tue, 18 May 2021, David Bremner <david@tethera.net> wrote:
> Jani Nikula <jani@nikula.org> writes:
>
>>
>> The Sphinx documentation on this [1] is confusing, and has the change
>> backwards. Git history says the default changed from False to True.
>>
>> [1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-man_make_section_directory
>
> Maybe the docs were corrected?
>
>     Changed in version 4.0: The default is changed to False from True.
                                                     ^^       ^^^^

Were you tricked by the funny word order? I know I was at first. :)

I looked deeper into the rabbit hole, and it really is a mess for such a
small change. They first added the config to create directories man/1
etc. in 3.3. Then they made it the default in 4.0. Then they realized
making it the default was a mistake, and are going to roll it back in
upcoming v4.0.2. Then they realized the directories should be named
man/man1 (not man/1) etc. and are going to change that in upcoming v4.1.

The patch at hand fixes the issue for v4.0.0 and v4.0.1 (the current
latest release). Are those worth catering for, I don't know. Up to you.

Actually using the feature would be really nice to avoid doing it
manually in the makefile, but then that would require Sphinx v3.3 and
having to take into account the directory name change in v4.1.

*facepalm*


BR,
Jani.


Some references:

https://github.com/sphinx-doc/sphinx/commit/178c05b0597e144fdc2117c7b46ac15723a290e8
https://github.com/sphinx-doc/sphinx/commit/a843fd3db8b588be93b576049a8a291bc4b3ec9d
https://github.com/sphinx-doc/sphinx/issues/7996
https://github.com/sphinx-doc/sphinx/issues/9217
https://github.com/sphinx-doc/sphinx/pull/9232
https://github.com/sphinx-doc/sphinx/pull/9231

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] doc: fix man page build for Sphinx 4.x
  2021-05-19  5:45   ` Jani Nikula
@ 2021-05-19 10:45     ` David Bremner
  0 siblings, 0 replies; 5+ messages in thread
From: David Bremner @ 2021-05-19 10:45 UTC (permalink / raw)
  To: Jani Nikula, notmuch

Jani Nikula <jani@nikula.org> writes:

> On Tue, 18 May 2021, David Bremner <david@tethera.net> wrote:
>> Jani Nikula <jani@nikula.org> writes:
>>
>>>
>>> The Sphinx documentation on this [1] is confusing, and has the change
>>> backwards. Git history says the default changed from False to True.
>>>
>>> [1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-man_make_section_directory
>>
>> Maybe the docs were corrected?
>>
>>     Changed in version 4.0: The default is changed to False from True.
>                                                      ^^       ^^^^
>
> Were you tricked by the funny word order? I know I was at first. :)

Oops, busted.

d

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH] doc: fix man page build for Sphinx 4.x
  2021-05-18 21:40 [PATCH] doc: fix man page build for Sphinx 4.x Jani Nikula
  2021-05-18 23:27 ` David Bremner
@ 2021-05-19 11:57 ` David Bremner
  1 sibling, 0 replies; 5+ messages in thread
From: David Bremner @ 2021-05-19 11:57 UTC (permalink / raw)
  To: Jani Nikula, notmuch; +Cc: jani

Jani Nikula <jani@nikula.org> writes:

> Sphinx 4.0 changed the default value of man_make_section_directory
> from False to True. We create the section directories and move the
> files manually, so fix the immediate man build failure by disabling
> the feature.
>
> The Sphinx documentation on this [1] is confusing, and has the change
> backwards. Git history says the default changed from False to True.

Applied to release and master.

d

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2021-05-19 11:57 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-18 21:40 [PATCH] doc: fix man page build for Sphinx 4.x Jani Nikula
2021-05-18 23:27 ` David Bremner
2021-05-19  5:45   ` Jani Nikula
2021-05-19 10:45     ` David Bremner
2021-05-19 11:57 ` David Bremner

Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).