Documentation overlays

[jroper]

Often we have to provide two sets of documentation, one for Java users, and one for Scala users. There are some pages that end up being shared between them. Attempts to include these in a single manual result in weird things like in Akka, it's very easy when navigating through the Java documentation to end up at the Scala documentation because you clicked a link to a shared page, and then clicked the next link which took you to something Scala specific.

Paradox should provide something that allows keeping the rendered manuals entirely separate, but allows sharing pages describing concepts, installation instructions, etc, between the two manuals. My suggestion would be to allow having a common directory, and then to "overlay" that directory with the language specific documentation. So for example:

manual
  - common
    - index.md
    - gettingstarted
      - installation.md
      - getting-started.md
  - java
    - actions
      - actions.md
      - routing.md
  - scala
    - actions
      - actions.md
      - routing.md

If done right, this can actually be very useful beyond just providing multiple programming languages to share resources, it can also be used for providing translations, as the translations can simply overlay the original, allowing things like code snippets from the original to be reused in the translations. We have successfully applied this approach in the Play documentation.

[drewhk]

On top of that, inclusion of common pages into two toctrees simply does not work. The linked page is only shown in one TOC but not the other.

[ktoso]

This is one of the bigger blockers for moving "Akka proper" onto paradox, right @drewhk ?

// cc @eed3si9n @pvlugter