auto-generated rst docs: top_srcdir vs top_builddir

[Nils Goroll]

Working on
https://www.varnish-cache.org/trac/changeset/5321145882f6edd65bbeae24a7ff23cc6985f57e/
I noticed that the same inconsistencies exist for the docs - authored vs. generated:

When srcdir != builddir, paths to generated rsts are wrong, so building in a
separate builddir does not work, e.g.:

# pristine source tree
slink at haggis:/tmp/varnish-cache$ mkdir build
slink at haggis:/tmp/varnish-cache$ cd build
slink at haggis:/tmp/varnish-cache/build$ ../configure
...
slink at haggis:/tmp/varnish-cache/build$ ../make
...
make[2]: Entering directory `/tmp/varnish-cache/build/man'
  CC       vsc2rst.o
  CCLD     vsc2rst
rst2man ../../doc/sphinx/reference/varnish-cli.rst varnish-cli.7
./vsc2rst | rst2man - varnish-counters.7
rst2man ../../doc/sphinx/reference/vcl.rst vcl.7
../../doc/sphinx/reference/vcl.rst:347: (SEVERE/4) Problems with "include"
directive path:
InputError: [Errno 2] No such file or directory:
'../../doc/sphinx/include/vcl_var.rst'.
Exiting due to level-4 (SEVERE) system message.
make[2]: *** [vcl.7] Error 1
make[2]: Leaving directory `/tmp/varnish-cache/build/man'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/tmp/varnish-cache/build'
make: *** [all] Error 2

I'd suggest the attached patch, but it is pretty useless as long as we can't use
dynamic paths in .rst like this (does not work! exemplary only!):

--- a/doc/sphinx/reference/vcl.rst
+++ b/doc/sphinx/reference/vcl.rst
@@ -344,7 +344,7 @@ In VCL you have access to certain variable objects. These
contain
 requests and responses currently being worked on. What variables are
 available depends on context.

-.. include:: ../include/vcl_var.rst
+.. include:: $(top_builddir)/doc/sphinx/include/vcl_var.rst


 Functions


Does anyone have a good solution here (except for "separate build directory not
supported")?

Nils
-------------- next part --------------
A non-text attachment was scrubbed...
Name: docs_srcdir_vs_builddir.patch
Type: text/x-patch
Size: 2855 bytes
Desc: not available
URL: <https://www.varnish-cache.org/lists/pipermail/varnish-dev/attachments/20140505/17a587ce/attachment.bin>