| Age | Commit message (Collapse) | Author |
|---|
|
These are generated indirectly by certain uses of python in the build.
|
|
Previously only man page aliases were being added as symlinks. The
addition to man_pages in conf.py automatically propagates to the list
of generated info pages.
Installation of the new pages is handled by existing recipes.
|
|
The previous defaults were not suitable for personal (i.e. not
bugtracking for notmuch development) use.
Provide two ways for the user to select nmbug compatible defaults;
command line argument and checking the name of the script.
|
|
In [1] Daniel observed that the gzipped man pages were only being
rebuild every second time when building with `make -j4'. This may be
caused by a race condition between sphinx-build rebuilding the roff
files and the recipe to gzip them. This commit sequentializes these
two steps by making the stamp file a prerequisite for (all of) the
gzip files.
[1]: id:87tveotn1g.fsf@fifthhorseman.net
|
|
This partially fixes (i.e. just for sphinx) the problem reported by
Daniel in id:87r29wwgq2.fsf@fifthhorseman.net.
|
|
Depending on a phony target seems like a good way to always trigger a
recipe.
|
|
Previously the python-cffi bindings either failed to build, or built
for the wrong module by using the installed module.
The fix requires correction the module path, building the bindings
before docs, and helping python find the built libnotmuch.
Based on patch / discussion from Micheal Gruber [1]
[1]: id:cover.1634808719.git.git@grubix.eu
|
|
Under a sufficiently high level of parallelism [1] there seems to be a
a race condition that allows sphinx-build to start running before the
docstrings are extracted. This change moves the docstring stamp from
the phony targets sphinx-html and sphinx-info to the file targets that
they depend on. I'm not sure why this makes things better, but I am
fairly confident it does not make things worse, and experimentally it
seems to eliminate the race condition.
[1]: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=976934
|
|
Use `makefile-gmake-mode' instead of `makefile-mode' because the
former also highlights ifdef et al. while the latter does not.
"./Makefile.global" and one "Makefile.local" failed to specify any
major mode at all but doing so is necessary because Emacs does not
automatically figure out that these are Makefiles (of any flavor).
|
|
It is getting unwieldy to pass configuration options on the
sphinx-build command line, and I anticipate further use of
conditionals.
As far as I could tell, execing a string is the idiomatic way to
emulate include in Python.
|
|
gzip includes the name of the uncompressed file and its modification
timestamp into the compressed archive. The latter makes it hard to
reproduce the generated files bit for bit at a later time, so omit this
information from the archive using the "--no-name" option. This is a
reproducibility best practice, see
https://wiki.debian.org/ReproducibleBuilds/TimestampsInGzipHeaders
|
|
The sphinx-doc include directive does not have the ability to include
files from the build tree, so we replace the include with reading the
files in conf.py. The non-trivial downside of this is that the emacs
docstrings are now defined for every rst source file. They are
namespaced with docstring::, so hopefully there will not be any
surprises. One thing that is noticable is a small (absolute) time
penalty in running sphinx-doc.
|
|
The extra flexibility of having both HAVE_EMACS (for yes, there is an
emacs we can use) and WITH_EMACS (the user wants emacs support) lead
to confusion and bugs. We now just force WITH_EMACS to 0 if no
suitable emacs is detected.
|
|
In 40b025 we stopped building the notmuch-emacs documentation if
HAVE_EMACS=0 (i.e. no emacs was detected by configure). Unfortunately
we continued to try to install the (non-existent) documentation, which
causes build/install failures.
As a bonus, we also avoid installing the documentation if the user
configures --without-emacs.
Thanks to Ralph Seichter for reporting the problem, and testing
previous versions of this fix.
|
|
Since the docstrings are not built in the case of --without-emacs,
even if emacs is detected, don't let sphinx build the emacs docs. This
avoids a large number of error messages due to missing includes. It's
actually a bit surprising sphinx doesn't generate an error for the
missing include files.
|
|
It seems our previous attempt with order-only targets was not
sufficient to avoid problems with sphinx-builds doctree cache [0].
Looking around at other people's approaches [1], using separate
doctrees was suggested. I guess there might be a slight loss of
efficiency, but it seems more robust.
[0]: build failures were first noticed in Debian experimental, but I was able to duplicate it in
my usual build environment about 1 in 8 builds.
[1]: in particular
https://salsa.debian.org/mpd-team/mpc/commit/9e3fc1657d043d75755993846c93f7700b97f907
|
|
This will still generate a warning about an excluded document in the
toctree, but it cuts down on the noise quite a lot.
|
|
These are less time consuming than the texi docs to rebuild (because
the texi rebuild triggers info rebuild), but still take noticable time.
|
|
Apparently the sphinx-doc texinfo builder is not smart enough to only
rebuild those files where the source has changed.
|
|
This should silence some warnings about the jobserver, but also make
it easier to build the docs where GNU make is called something other
than make.
Based on a patch from aidecoe.
|
|
Changes from 0.28.3
|
|
In certain conditions the parallel calls to sphinx-build could
collide, yielding a crash like
Exception occurred:
File "/usr/lib/python3/dist-packages/sphinx/environment.py", line 1261, in get_doctree
doctree = pickle.load(f)
EOFError: Ran out of input
|
|
This is nonsensical on the face of it, but is needed (for now) because
the notmuch-emacs page is unconditionally included in index.rst.
|
|
We need to use the stamp file here in order not to depend on the order
the submakefiles are included.
|
|
All of the man pages are installed as info pages, plus
the (unfinished) notmuch-emacs manual
|
|
Avoids the issue where umask can make man pages unreadable after
installation. Relevant email on the mailing-list:
<87h8rt30sy.fsf@fifthhorseman.net>
|
|
Install man pages based on $(MAN_GZIP_FILES), which directly
corresponds to the man page source rst files. This way we can filter
the man pages to be installed as needed.
|
|
Use $(wildcard ...) to generate the list of man pages based on the rst
source files present in the man page directories, instead of reading
conf.py. This has three main benefits:
1) This makes the man page build slightly less complicated and easier
to understand. At least there are fewer moving parts.
2) This makes the build fail if we add a man page rst file, but fail
to add it to conf.py.
3) We can use Sphinx constructs in conf.py that are not available when
importing the file into a normal python program such as
mkdocdeps.py.
|
|
If Sphinx fails to create any of the roff files, having touch create
them hides the errors until someone realizes, possibly much later,
that the resulting files are empty. (Note that gzip doesn't fail on
empty input files.) Sphinx will change the timestamps of any files it
has written anyway.
|
|
Thanks to FreeBSD port maintainer Mikhail for report and the original
the original patch.
This is the right thing (TM) and also apparently fixes the build on
FreeBSD.
|
|
If HAVE_SPHINX=0 but HAVE_DOXYGEN=1, then the previous version was
trying to install notmuch.3.gz but only got as far as creating
notmuch.3
|
|
It was becoming increasingly complicated to support rst2man, and there
were apparently not many people that relied on it.
|
|
Some (older) Doxygen versions do not create such a temporary file.
|
|
There is a doxygen bug about these odd files,
https://bugzilla.gnome.org/show_bug.cgi?id=727796
But it isn't clear if / when a fix will be provided, so just delete it
to avoid e.g. confusing man-to-wiki.pl
|
|
Remove excess italics from doxygen output. It seems to make no
sense (and is certainly ugly) to italicize the first argument to the
.RI macro.
|
|
In order to support out of tree builds and avoid hardcoding version
number, generate `doc/config.dox` from configure.
|
|
This build artifict messes up the packaging process for (at least)
Debian if not removed on clean.
|
|
The roff build rule builds all of the roff files in a single command.
Previously, this was expressed as a multi-target rule, but since this
is equivalent to specifying a copy of the rule for each target, make
-jN could start up to N parallel instances of this command. Fix this
by bottlenecking this rule through a single stamp file.
This also removes the unused man.stamp from CLEAN.
|
|
The subtle part is adding .rst and .py files to vpath so they can be
used as dependencies without prefixing with $(srcdir)
We also change the interface to mkbuildeps.py: rather than getting the
containing directory from the conf file path, we go the other way.
|
|
Because sphinx-build does not provide a convenient way of listing
which builders exist, and some people actually have pre 1.0 sphinx, we
try loading a relevant python module.
Currently the assumption is that no python in path -> no sphinx-build
in path.
|
|
It turns out there was a reason the old man pages were stored in a man
compatible hierarchy, namely so that we could run man on them before
installing.
Hardcode doc build location into test suite. This isn't ideal, but
let's unbreak the test suite for now.
|
|
This helps avoid build artifacts (namely, nroff and gzipped-nroff man
pages) owned by root.
The variables allow choosing which generator to use for the man page.
These will be hooked to configure in a following commit.
|
|
The python script mkdocdeps.py is used to import the list of man pages
from the sphinx configuration to make.
This will delete the (release only) target update-man-versions. This
will be replaced in a followup commit.
|
|
Many people have docutils installed, but not sphinx. Allow these
people to build the man pages.
|
|
This is the output from sphinx-quickstart, massaged a bit, along with
our existing man pages converted to rst.
A skeleton notmuch-emacs manual is also included. It is not suitable
for end user use yet.
|
