Restrictions on containment director for out of source build using cmake

[dirkcgrunwald]

I need to use an out of source build in Cmake for a particular C++ project.

I've modified my CMakefile and my breathe conf.py to use template conf.py.in and generate the appropriate paths.

However, when I run sphinx with exhale I get the restriction

The given containmentFolder [/some/project/build/docs/api] must be a SUBDIRECTORY of [/some/project/docs].

according to the source in exhale/configs.py this error is to prevent poorly configured projects.

Is there an example of using exhale with cmake and out of source builds (i.e. mkdir build ; cd build ; cmake .. )?

[svenevs]

Quick comment from a phone, please excuse typos / terse. I doubt it will work even if you comment out the code in exhale that stops you

https://github.com/sphinx-doc/sphinx/issues/3132

There is and likely always only will be one available "source directory", and you can't make sphinx read additional sources from anywhere else. When you run sphinx-build it populates app.srcdir. Sphinx multibuild linked in the issue works well to my recollection of playing with it long ago, so that may be what you need to use depending on your goal.

1. Are you trying to ultimately build two separate projects, one from repo/docs and one from build/docs? If so only the one in build/docs can reference exhale, and your cmake configure should point containment folder to build/docs/api. You could then build each separately, or do sphinx multibuild.
2. More likely. You just want to build one set of docs. Your cmake setup should copy repo/docs to build/docs (build can be in tree or out of tree), configure conf.py.in and set containment folder using e.g. ${CMAKE_CURRENT_BINARY_DIR}/docs/api, and invoke sphinx-build on the build tree (not repo/docs). If you're using a custom command to call sphinx-build make sure to set the right working directory (to the build tree).

The check from exhale commented out would just result in the files being generated, but sphinx ignoring it? It really all depends on what you are running where.

I have some changes stashed on that configuration variable to relax the requirements a bit so I can take a look at throwing together a brief cmake example. Is your code public? If so drop a link and I'll test it out on your repo. I think there's other things exhale is too picky about that would be good to relax, especially for cmake builds. I know I've done a cmake builds in the past but don't remember what I did and should definitely document it more.

[svenevs]

I am closing this as the restriction cannot be lifted, it's a requirement of sphinx. I relaxed the constraints in #144 to allow any subdirectory of docs/ (app.srcdir) directory, but where CMake is concerned you have to generate a docs/ directory in your build tree.