Add choice element rendering in documentation

[mretegan]

This PR adds support for rendering <choice> elements in the HTML documentation and ensures that all elements (fields, groups, choices, links) are rendered in their original XML document order. Closes #1439

[woutdenolf]

@PeterC-DLS Any idea why the CI does not get executed?

[PeterC-DLS]

We have chosen to set the Approval rule for running fork PR workflows to "Only users who have never had a commit or pull request merged into this repository will require approval to run workflows" - see (https://docs.github.com/en/actions/how-tos/manage-workflow-runs/approve-runs-from-forks)

[woutdenolf]

I don't seem to have permissions to give approval unless I'm missing something.

[PeterC-DLS]

Perhaps they can try rebasing it

[woutdenolf]

The "choice" docs are now showing up like this:

[woutdenolf]

The diff is very hard to read but as I understand instead of doing a for-loop for each tag, we do one loop for all tags and use an if-statement to distinguish between tags. And we do this to keep the order as defined in the XML file.

[woutdenolf]

@mretegan Why do we need to preserve the order here?

[mretegan]

It felt like the normal thing to do. There is always some logic behind the order in which people list things in the XML, so I think it should be kept in the HTML rendering. When I first added the <choice> rendering, I was surprised to see it at the end.

[woutdenolf]

There is always some logic behind the order in which people list things, so I think it should be kept in the HTML rendering.

But it could have been an explicit choice to systematically group fields, groups, links etc. in the HTML docs. The order within each group is still kept. Do you know @PeterC-DLS @prjemian ?

[woutdenolf]

Apart from refactoring the way we extract tag names (group, field, attribute, link, choice) from XML nodes it looks good.

Edit: I'll refactor the tag stuff in another PR.

[woutdenolf]

@PeterC-DLS This is a fix for showing choice tags in the HTML docs. Do you mind we merge this before the patch release or wait till after (better safe than sorry)?