Open Stack

> The publishing job is just code and can be adapted to publish two (three) 
> subtrees to different places, or exclude some directories.
> The global index files from doc/source do not necessarily need to include all 
> the index files of the subdirectories, so that shouldn't be a problem.
> 
> Do you have a specific concern that it may difficult to address?
> 

As Doug pointed out, it is very difficult to split out a generated set of
documentation from Sphinx. There are too many links between the resulting
output.

Assuming that is possible, the existing standard set of jobs for publishing
these to their respective locations cannot handle this. It would be a
non-standard thing (unless all repos switched over to this new structure) so it
would not be able to run the jobs that are expected of all projects.

We would also need to update the published documentation for how this should be
done here:

https://governance.openstack.org/tc/reference/project-testing-interface.html#documentation

If the desire is to better organize documentation files within the repo, I
could see potentially having being able to more easily do something where you
have doc/source, doc/api-ref, and doc/releasenotes. But the few things
mentioned above would need to be updated to allow that.