decrease folder level of docs in submodules

[danstender]

Hi Maciej,
I've begun to work on packaging also this repo as debops-doc package for Debian
(https://bugs.debian.org/820367), but there's an obstacle with the submodules. The
folders in docs/ contain the whole repositories, therefore a massive debian/copyright file
covering everything else not needed for the docs would be necessary for that package,
not to speak the upstream tarball of that package would be massive, containing mostly
unneeded stuff. Could you find a way that e.g. docs/debops/ contains debops/debops/docs/,
that would be very nice .... (you've talked about git-subrepo in https://bugs.debian.org/819816,
is there a perspective with that?

[drybjed]

Right now part of the Sphinx documentation is generated by yaml2rst script which converts defaults/main.yml of different roles from YAML to reStructuredText, which then is included in finished ReadTheDocs build. This is done so that documentation can be very easily updated with current default variables if anything changes.

I realize that this approach might not be optimal for packaging all of the documentation from all of the different repositories in one package.Actually now that I think of it, if you packaged all of the roles in debops-playbooks package, you basically included the documentation in there as well, although not in a compiled state... Hmmm. Submodules are supported by ReadTheDocs automatically, not sure if something similar would be possible with git-subrepo, perhaps maybe on a custom RTD install.

Is there a way do build the documentation package somehow (think like compiling a binary package from source)? Or should I look into making the documentation differently? I was looking into making SGML-style documentation, but that seems a bit overkill, and I guess default variables would need to be somehow converted into that format as well.