Read the Docs does offer a feature that allows using config file in order to point to specific repositories, that contains documentation content. However, Read the Docs requires specific configuration to be used in order to make that work.

Since we decided that we want to use MkDocs with RtD we needed to find a way to reach this effect without the specific config. In order to achieve that we need to to use an auxiliary software that allows for scanning through our repositories in search for documentation folders (name proposition docu ) and merge them into one documentation repository.

During research, several approaches to this topic were found, but most of them are tied to automation build servers like Bamboo or Jenkins, using them to collect docs and trigger static web page generation and deployment.
Part of those tasks are covered by Read the Docs itself, but it is quite difficult to make it work smoothly, according to our experiments.

However, eZ Products uses such kind of architecture already - for the i18n-translation packages management. It's called git-subsplit and allows to collect files from several locations in different repositories.
One of the concerns here is the cost of setup and maintenance - will it be managed by doc-squad or IT Team?

• See RTD Documentation: subprojects (http://docs.readthedocs.io/en/latest/subprojects.html)
• See i18n translation repository (https://github.com/ezsystems/ezplatform-i18n)

--------

Pros/Cons

green = pros
red = cons
orange = duty

Unique, separated doc repo

Doc organized according to the reader logic/learning process, not according to the app structure
Doc Squad has to maintain releases-dependant doc
Users have to browse the Doc website or the doc-repository
Doc Squad could manage and merge pull requests on their own
Easier to port existing doc (no need to distribute what we have now around a dozen repos)

Projects respositories

Need to split existing (longer) pages into different repos and then merge them together in output
Doc more closely bound to the software release process
Doc Squad would have to request & wait for merges from managers of each repository
Quicker and easier for the devs to ship doc
Doc contained in private repos (enterprise edition) would not be available to readers on GH itself (also for contribution)
Users will get the doc along the code when cloning the repository