Package: src:sphinx Version: 1.8.4-1 Severity: normal -M option doesn't work well except for a very simple case. I faced this problem while building multi-language source.
Let me illustrate most gross case with gettext.
Most simple case:
$ sphinx-build -M gettext source build
This creates:
new file: build/gettext/.doctrees/environment.pickle
new file: build/gettext/.doctrees/index.doctree
new file: build/gettext/.doctrees/scope.doctree
new file: build/gettext/index.pot
new file: build/gettext/scope.pot
It forces to use build/gettext as destination and build/gettext/.doctrees
as cache directory. Although not elegant, I can live with this for now.
I wanted to move the cache directory to a particular FOO, so I did:
$ sphinx-build -M gettext -d FOO source build
This creates:
new file: FOO/gettext/environment.pickle
new file: FOO/gettext/index.doctree
new file: FOO/gettext/scope.doctree
new file: build/index.pot
new file: build/scope.pot
Hmmm... I didn't expect this. Other command usually put these cached
files just under FOO/ not under FOO/gettext/ . That is what -d option
works.
So I switched to use -b option instead of -M which behaves sanely.
$ sphinx-build -b gettext -d FOO source build
This creates:
new file: FOO/environment.pickle
new file: FOO/index.doctree
new file: FOO/scope.doctree
new file: build/index.pot
new file: build/scope.pot
Yah, this is what I expects.
FYI: I now use followings to share cached files for i18n build.
$ sphinx-build -b gettext source/locales -d build/en source build/en
$ sphinx-build -b html -d build/en source build/en/html
$ sphinx-build -b epub -d build/en source build/en/epub
...
I attach example scripts as tared git repo with history.
-- System Information:
Debian Release: 10.0
APT prefers stable
APT policy: (500, 'stable')
Architecture: amd64 (x86_64)
Kernel: Linux 4.19.0-5-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8),
LANGUAGE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
gettext-sphinx.tar.gz
Description: application/gzip
