Links forged from top-level NodesSelector structures are incorrect
g-pavlov opened this issue · comments
What happened:
When using a single top-level nodesSelector, links to other documentation structure nodes are not rewritten to relative. They are converted to absolute.
What you expected to happen:
Links to nodes from a document structure are always relative. A top-level nodesSelector gets resolved to node structure and this applies to its document nodes as well.
How to reproduce it (as minimally and precisely as possible):
Execute a docforge build with this manifest:
nodesSelector:
path: https://github.com/gardener/gardener/tree/master/docs
e.g.:
docforge -f manifest.yaml -d /tmp/1234-test --github-oauth-token $GITHUB_TOKEN
or add the --dry-run option to analyze links rewriting.
Either way, inspect the README.md file in the destination path /tmp/1234-test. All links are absolute, including the ones to other documents that should be resolved as nodes, because they are in the nodesSelector path.
Anything else we need to know:
Note, that the problem is observed only for top-level nodesSelector. With a manifest like this:
structure:
- name: gardener
nodesSelector:
path: https://github.com/gardener/gardener/tree/master/docs
links are rewritten correctly.
The root cause of the issue seems to be that with a top-level nodesSelector, the root node is not resolved (see the screenshot below). It features only a single nodesSelector property and no nodes. However, its direct descendants point to it as parent. The search mechanism for other nodes that is involved in resolving links to relative/absolute attempts to search from that root and since it has no child Nodes it doesn't descent any further, always resulting in absolute links resolution.
How to categorize this issue?
/kind bug
/priority critical
Debugging further it turned out that we have a general problem in finding out nodes in peer branches in the Structure array because the top-level nodes in the array do not share a common root node. That affects the generation of relative paths. the problem outlined in this issue has similar issue - in this particular case a root node is set, but only halfway without constructing the downstream hierarchy.