Either fix or comment how to specify a templates_path.

[rkent]

In conf.py I managed to get a template to work, but it was ugly:

templates_path = ['../../../../../_templates']

This is of course a consequence of the issue mentioned elsewhere, that relative directories don't work in conf.py. You really have to get into the guts of how all of the pieces work to get this correct. It also does not really match what the comment says:

# Add any paths that contain templates here, relative to this directory.

That is only correct if indeed you understand that it is relative to where conf.py will be when it moves.

We either need to somehow document this, or figure out how to copy the templates folder into the same relative position to the actual place where conf.py is invoked.

[aprotyas]

As you noted, this relative path idea is quite counterintuitive. It's also flaky because the relative path right now depends on where the conf.py is displaced and/or invoked from.

I don't have a good solution for this now, but I had a similar thought as you did: the "relative"-ness of the templates_path between the source conf.py and the invoked conf.py needs to stay the same.

[rkent]

One possible approach to this is to run conf.py in its original position, then extract the variables from there. Then get all paths, and make sure they are absolute. See https://github.com/rkent/rosdoc2/tree/prerun_conf_py for an implementation of this. That works for me, with conf.py in doc folder, and templates_path = ['_templates']

One downside of that the original conf.py can manipulate tags. From the documentation:

There is a special object named tags available in the config file. It can be used to query and change the tags (see Including content based on tags).

I suspect though that this is not common.