Multiple `nodesSelector` in the same node

[Georgi Pavlov]

What would you like to be added:
The ability to mash up hierarchical structures from various origins under the same node using nodesSelector specifications, e.g. by introducing a nodesSelectors (note the plural) element to the API. A nodesSelectors is defined as a list of nodesSelector elements.

Example:

Mashup the gardener and machine-controller-manager documentation under a Guides container node. In addition, each nodesSelector may introduce their own specific filter criteria.

structure:
- name: Guides
  nodesSelectors:
  - path: https://github.com/gardener/machine-controller-manager/blob/master/.docforge/manifest.yaml
  nodesSelectors:
  - path: https://github.com/gardener/gardener/blob/master/.docforge/manifest.yaml 

Handling naming conflicts:

The nodesSelector mechanism is meant as a solution when its path targets are controlled, i.e. we have the control to avoid naming conflicts in the first place. However, it is common that documentation follows the same governance rules including naming conventions and structure. In the example above, both locations may share top level structure nodes at the very least, e.g. Usage, Development, etc. In theory it is possible that a whole branch in the hierarchy is the same path as far as node names are concerned. That presents the challenge how to reconcile such conflicts.

A solution to the conflicting paths resolution problem is to apply merge strategy for the container nodes on each path when their names are the same. When there are files that have conflicting names, the strategy is to apply a rename pattern to either of the files (e.g. a.md -> a_1.md or a.md -> a (1).md). The pattern can be a configuration option.

While this solves the problem from path resolution perspective, it is notable that it will resent certain presentation challenges. For example, using such source with the --hugo options and without any further metadata will leave no other option but inject a title in the file frontmatter based on that name (e.g. a.md -> a_1.md -> title: a 1), which may look strange. Then again, this is a tradeoff between agility and control that may or may not be acceptable in different use cases. A post-processing task to adapt such titles may be employed, if a more sophisticated mechanism for naming is required.

Finally, having conflicts on section files (_index.md) is probably the biggest challenge in two aspects:

• Choosing the file that will serve the purpose to present information about a section when there are multiple ones on the same node.
  There really isn't any good way to guess that and by default the behavior should be to not make any assumptions about that. Normally, the answer to that would be to switch to an explicit structure, if it is important. However, this is unfortunately a very common scenario. An option to handle this while preserving the nodesSelector abstraction is with a little help from the ordering of the node selectors. The proposed nodesSelectors structure is an array. A solution to the problem could be to take the previous nodesSelector in order (if any) as normative.
• The notion of a section file is not part of the structure resolution process currently.
  A file is resolved as a section file based on the --hugo-section-files flag and its name on a much later stage. This needs to change and resolve potential section files as part of the whole structure resolution process.

Why is this needed / describe a real-world scenario:
Currently, it is not possible to mashup the contents of two containers using the nodesSelector abstractions. This requires manual to fall back to explicit structure definitions. Therefore it is not possible to delegate structure definitions as reusable modules to content owners and take advantage of it if it is necessary to model modules not as peer nodes but as a single node.

How to categorize this?:
/kind enhancement
/priority normal

[Kristian Zhelyazkov]

Not a relevant after the refactoring

/close