Proposal for how to implement the docs reorg proposal

[gerolf-da]

The changes in this PR are based on the original docs reorg document.

Understanding what changed compared to the previous setup

Live Preview

The live preview script creates symlinks for the index folder and the index_html.rst into the build directory.
This means that within the .rst files in this repository, all canton content can be linked to with /canton, all SDK content with the respective root level folder, e.g. /getting-started, and all custom index files with /index.

Structure

The staring point is index_html.rst. This is where the main structure / top-level menu items are contained.

Single level of content

When the doc structure asks for only one level of content, like the Set Up Your Environment section, then the sphinx documents from either Canton or SDK can be linked directly into index_html.rst. See index_html.rst#25-34.

Multiple levels of content

For more than one level of content, like Create Daml Apps, the structure is modeled within this repository as a folder structure containing index.rst files.
So, for the target structure

| Create Daml Apps
|--- Developer Tools
|   |--- Introduction
|   |--- Basic Contracts
|   |--- ...
|--- Integrate Daml with Off-Ledger Services
|   |-- Introduction
|   |--- Access Active Contracts with the HTTP JSON API Service
|   |--- ...

the following folder structure is used:

The top-level menu Create Daml Apps in index_html.rst refers to the index.rst files in the sub-folders (e.g. for linking to developer tools), which in turn contain a table of content that points to the already existing pages from the canton or SDK docs (see /index/create-daml-apps/developer-tools/index.

Required Changes in the Canton or SDK docs

Because of how Sphinx renders the menu for the current document, documents should only be linked to from a single toctree directive. In case a document that is covered by this example/PoC is already contained in such a toctree directive, I left a comment in the corresponding index.rst file in this repository that it needs to be removed in the original original toctree. See docs/index/create-daml-apps/off-ledger/json-api/index.rst as example.